doc bits

doc/source/modules/service/detect.rst

@@ -0,0 +1,103 @@
+.. BACpypes change detection module
+
+.. module:: detect
+
+Detect
+======
+
+This is a long line of text.
+
+Classes
+-------
+
+
+.. class:: DetectionMonitor
+
+    .. attribute:: algorithm
+    .. attribute:: parameter
+    .. attribute:: obj
+    .. attribute:: prop
+    .. attribute:: filter
+
+    .. method:: __init__(algorithm, parameter, obj, prop, filter=None)
+
+        This is a long line of text.
+
+    .. method:: property_change(old_value, new_value)
+
+        This is a long line of text.
+
+.. class:: DetectionAlgorithm
+
+    .. attribute:: _monitors
+
+        This private attribute is a list of `DetectionMonitor` objects that
+        associate this algorithm instance with objects and properties.
+
+    .. attribute:: _triggered
+
+        This private attribute is `True` when there is a change in a parameter
+        which causes the algorithm to schedule itself to execute.  More than
+        one parameter may change between the times that the algorithm can
+        execute.
+
+    .. method:: __init__()
+
+        Initialize a detection algorithm, which simply initializes the
+        instance attributes.
+
+    .. method:: bind(**kwargs)
+
+        :param tuple kwargs: parameter to property mapping
+
+        Create a `DetectionMonitor` instance for each of the keyword arguments
+        and point it back to this algorithm instance.  The algorithm parameter
+        matches the keyword parameter name and the parameter value is an
+        (object, property_name) tuple.
+
+    .. method:: unbind()
+
+        Delete the `DetectionMonitor` objects associated with this algorithm
+        and remove them from the property changed call list(s).
+
+    .. method:: execute()
+
+        This function is provided by a derived class which checks to see if
+        something should happen when its parameters have changed.  For example,
+        maybe a change-of-value or event notification should be generated.
+
+    .. method:: _execute()
+
+        This method is a special wrapper around the `execute()` function
+        that sets the internal trigger flag.  When the flag is set then the
+        `execute()` function is already scheduled to run (via `deferred()`)
+        and doesn't need to be scheduled again.
+
+Decorators
+----------
+
+.. function:: monitor_filter(parameter)
+
+    :param string parameter: name of parameter to filter
+
+    This decorator is used with class methods of an algorithm to determine
+    if the new value for a propert of an object is significant enough to
+    consider the associated parameter value changed.  For example::
+
+        class SomeAlgorithm(DetectionAlgorithm):
+        
+            @monitor_filter('pValue')
+            def value_changed(self, old_value, new_value):
+                return new_value > old_value + 10
+
+    Assume that an instance of this algorithm is bound to the `presentValue`
+    of an `AnalogValueObject`::
+    
+        some_algorithm = SomeAlgorithm()
+        some_algorithm.bind(pValue = (avo, 'presentValue'))
+
+    The algorithm parameter `pValue` will only be considered changed when
+    the present value of the analog value object has increased by more than
+    10 at once.  If it slowly climbs by something less than 10, or declines
+    at all, the algorithm will not execute.
+