From 5869d095a466c3f5a2eeb4ebfae89a41cca69b0c Mon Sep 17 00:00:00 2001
From: Dane Finlay <Danesprite@posteo.net>
Date: Sat, 12 Oct 2019 17:12:35 +1100
Subject: [PATCH] Add missing documentation on recognition observers

Re: #77.
---
 documentation/object_model.txt        |  1 +
 documentation/recobs.txt              | 26 +++++++++++++++
 documentation/test_recobs_doctest.txt |  6 +++-
 dragonfly/grammar/recobs.py           | 46 ++++++++++++++++++++++++++-
 4 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 documentation/recobs.txt

diff --git a/documentation/object_model.txt b/documentation/object_model.txt
index cedb9686..597681b1 100644
--- a/documentation/object_model.txt
+++ b/documentation/object_model.txt
@@ -13,6 +13,7 @@ object model.
     rules
     elements
     context
+    recobs
 
 
 Grammars
diff --git a/documentation/recobs.txt b/documentation/recobs.txt
new file mode 100644
index 00000000..f2c2e638
--- /dev/null
+++ b/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.
diff --git a/documentation/test_recobs_doctest.txt b/documentation/test_recobs_doctest.txt
index e3ada093..7ea6afb4 100644
--- a/documentation/test_recobs_doctest.txt
+++ b/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.
diff --git a/dragonfly/grammar/recobs.py b/dragonfly/grammar/recobs.py
index dd924d7f..1cdea65b 100644
--- a/dragonfly/grammar/recobs.py
+++ b/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,9 +127,11 @@ 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:
@@ -108,12 +139,25 @@ def on_recognition(self, words):
                 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)