Add missing documentation on recognition observers

Re: #77.

documentation/object_model.txt

@@ -13,6 +13,7 @@ object model.
     rules
     elements
     context
+    recobs
 
 
 Grammars

documentation/recobs.txt

@@ -0,0 +1,26 @@
+.. _Recobs:
+
+Recognition observers
+============================================================================
+
+This section describes classes and functions for observing Dragonfly's
+recognition state events:
+
+ * ``on_begin()`` -- called when speech start is detected.
+ * ``on_recognition()`` -- called when speech successfully decoded to a
+   grammar rule or to dictation. This is called *before* grammar rule
+   processing (i.e. ``Rule.process_recognition()``).
+ * ``on_failure()`` -- called when speech failed to decode to a grammar rule
+   or to dictation.
+
+.. automodule:: dragonfly.grammar.recobs
+   :members:
+
+.. automodule:: dragonfly.grammar.recobs_callbacks
+   :members:
+
+Doctest usage examples
+----------------------------------------------------------------------------
+
+See Dragonfly's :ref:`doctests for recognition observers<Recobs Doc Tests>`
+for some usage examples.

documentation/test_recobs_doctest.txt

@@ -1,7 +1,11 @@
-
+.. _Recobs Doc Tests:
+
 RecognitionObserver base class
 ==========================================================================
 
+If you're looking for the class and function reference for recognition
+observers, you want :ref:`this page <Recobs>`.
+
 .. note:: :class:`RecognitionObserver` instances can be used for both
    the DNS and the WSR backend engines.  However, WSR will sometimes call
    observer methods multiple times, so be careful using observers with it.

dragonfly/grammar/recobs.py

@@ -19,7 +19,7 @@
 #
 
 """
-Recognition observer base class
+Recognition observer classes
 ============================================================================
 
 """
@@ -36,6 +36,11 @@
 #---------------------------------------------------------------------------
 
 class RecognitionObserver(object):
+    """
+    Recognition observer base class.
+
+    Sub-classes should override one or more of the event methods.
+    """
 
     _log = logging.getLogger("grammar")
 
@@ -49,20 +54,44 @@ def __del__(self):
             pass
 
     def register(self):
+        """
+        Register the observer for recognition state events.
+        """
         engine = get_engine()
         engine.register_recognition_observer(self)
 
     def unregister(self):
+        """
+        Unregister the observer for recognition state events.
+        """
         engine = get_engine()
         engine.unregister_recognition_observer(self)
 
     def on_begin(self):
+        """
+        Method called when the observer is registered and speech start is
+        detected.
+        """
         pass
 
     def on_recognition(self, words):
+        """
+        Method called when speech successfully decoded to a grammar rule or
+        to dictation.
+
+        This is called *before* grammar rule processing (i.e.
+        ``Rule.process_recognition()``).
+
+        :param words: recognized words
+        :type words: tuple
+        """
         pass
 
     def on_failure(self):
+        """
+        Method called when speech failed to decode to a grammar rule or to
+        dictation.
+        """
         pass
 
 
@@ -98,22 +127,37 @@ def complete(self):
         return self._complete
 
     def on_begin(self):
+        """"""
         self._complete = False
 
     def on_recognition(self, words):
+        """"""
         self._complete = True
         self.append(self._recognition_to_item(words))
         if self._length:
             while len(self) > self._length:
                 self.pop(0)
 
     def _recognition_to_item(self, words):
+        """"""
         return words
 
 
 #---------------------------------------------------------------------------
 
 class PlaybackHistory(RecognitionHistory):
+    """
+        Storage class for playing back recent recognitions via the
+        :class:`Playback` action.
+
+        Instances of this class monitor recognitions and store them
+        internally.  This class derives from the built in *list* type
+        and can be accessed as if it were a normal *list* containing
+        :class:`Playback` actions for recent recognitions.  Note that an
+        instance's contents are updated automatically as recognitions are
+        received.
+
+    """
 
     def __init__(self, length=10):
         RecognitionHistory.__init__(self, length)