docu update for fader (new features explained)

doc/user/source/referenz/items/funktionen.rst

@@ -23,11 +23,13 @@ genutzt werden können.
 |                                | :doc:`autotimer <./standard_attribute/autotimer>`                              |
 |                                | nachlesen.                                                                     |
 +--------------------------------+--------------------------------------------------------------------------------+
-| fade(end, step, delta)         | Blendet das Item mit der definierten Schrittweite (int oder float) und         |
-|                                | timedelta (int oder float in Sekunden) auf einen angegebenen Wert auf oder     |
-|                                | ab. So wird z.B.: **sh.living.light.fade(100, 1, 2.5)** das Licht im           |
+| fade(end, step, delta,         | Blendet das Item mit der definierten Schrittweite (int oder float) und         |
+|   stop_fade, continue_fade,    | timedelta (int oder float in Sekunden) auf einen angegebenen Wert auf oder     |
+|   instant_set, instant_update) | ab. So wird z.B.: **sh.living.light.fade(100, 1, 2.5)** das Licht im           |
 |                                | Wohnzimmer mit einer Schrittweite von **1** und einem Zeitdelta von **2,5**    |
-|                                | Sekunden auf **100** herunterregeln.                                           |
+|                                | Sekunden auf **100** herunter regeln. Bei manueller Änderung wird der Prozess  |
+|                                | gestoppt. Dieses Verhalten kann jedoch durch stop_fade oder continue_fade      |
+|                                | geändert werden. Genaueres dazu ist in den Beispielen unten zu finden.         |
 +--------------------------------+--------------------------------------------------------------------------------+
 | remove_timer()                 | Entfernen eines vorher mit der Funktion timer() gestarteten Timers ohne dessen |
 |                                | Ablauf abzuwarten und die mit dem Ablauf verbundene Aktion auszuführen.        |
@@ -135,8 +137,28 @@ Die folgende Beispiel Logik nutzt einige der oben beschriebenen Funktionen:
    sh.item.autotimer()
 
    # will in- or decrement the living room light to 100 by a stepping of ``1`` and a timedelta of ``2.5`` seconds.
+   # As soon as the item living.light gets changed manually, the fader stops.
    sh.living.light.fade(100, 1, 2.5)
 
+Die folgenden Beispiele erläutern die fade-Funktion im Detail.
+Beispiel 1: Der Fade-Prozess wird nur gestoppt, wenn ein manueller Item-Wert über das Admin-Interface
+angegeben wurde. Wird das Item anders aktualisiert, wird der nächste Fade-Wert sofort gesetzt.
+Beispiel 2: Der Fade-Prozess wird durch sämtliche manuelle Item-Änderungen gestoppt, außer die Änderung
+kommt von einem Caller, der "KNX" beinhaltet.
+Beispiel 3: Der Fade-Prozess wird bei jeder manuellen Item-Änderung gestoppt.
+
+   .. code-block:: python
+      :caption:  logics/fading.py
+
+      # erstes Beispiel
+      sh.living.light.fade(100, 1, 2.5, stop_fade=["admin"], instant_update=True)
+
+      # zweites Beispiel
+      sh.living.light.fade(100, 1, 2.5, continue_fade=["KNX"])
+
+      # drittes Beispiel
+      sh.living.light.fade(100, 1, 2.5)
+
 Der folgende Beispiel eval Ausdruck sorgt dafür, dass ein Item den zugewiesenen Wert nur dann übernimmt,
 wenn die Wertänderung bzw. das Anstoßen der eval Funktion über das Admin Interface erfolgt ist und das
 letzte Update vor der aktuellen Triggerung über 10 Sekunden zurück liegt.

lib/item/helpers.py

@@ -251,6 +251,10 @@ def cache_write(filename, value, cformat=CACHE_FORMAT):
 # Fade Method
 #####################################################################
 def fadejob(item, dest, step, delta, stop_fade, continue_fade, instant_set, instant_update):
+    """
+    fades an item value to a given destination value
+
+    """
     def check_external_change(entry_type, entry_value):
         matches = []
         for pattern in entry_value:

lib/item/item.py

@@ -2588,6 +2588,17 @@ def autotimer(self, time=None, value=None, compat=ATTRIB_COMPAT_LATEST):
 
 
     def fade(self, dest, step=1, delta=1, stop_fade=None, continue_fade=None, instant_set=True, instant_update=False):
+        """
+        fades an item value to a given destination value
+
+        :param dest: destination value of fade job
+        :param step: step size for fading
+        :param delta: time interval between value changes
+        :param stop_fade: list of callers that can stop the fading (all others won't stop it!)
+        :param continue_fade: list of callers that can continue fading exclusively (all others will stop it)
+        :param instant_set: If set to True, first fade value is set immediately after fade method is called, otherwise only after delta time
+        :param instant_update: If set to True, an ongoing fade will update a manually changed item value instantly, otherwise after delta time
+        """
         if stop_fade is None:
             stop_fade = []
         if continue_fade is None: