Document FSMManagingEventHandler

lib/tfw/components/fsm_managing_event_handler.py

@@ -9,6 +9,20 @@ LOG = logging.getLogger(__name__)
 
 
 class FSMManagingEventHandler(EventHandlerBase):
+    """
+    EventHandler responsible for managing the state machine of
+    the framework (TFW FSM).
+
+    tfw.networking.TFWServer instances automatically send 'trigger'
+    commands to the event handler listening on the 'fsm' key,
+    which should be an instance of this event handler.
+
+    This event handler accepts messages that have a
+    data['command'] key specifying a command to be executed.
+
+    An 'fsm_update' message is broadcasted after every successful
+    command.
+    """
     def __init__(self, key, fsm_type, require_signature=False):
         super().__init__(key)
         self.fsm = fsm_type()
@@ -34,6 +48,12 @@ class FSMManagingEventHandler(EventHandlerBase):
             LOG.error('IGNORING MESSAGE: Invalid message received: %s', message)
 
     def handle_trigger(self, message):
+        """
+        Attempts to step the FSM with the supplied trigger.
+
+        :param message: TFW message with a data field containing
+                        the action to try triggering in data['value']
+        """
         trigger = message['data']['value']
         if self._require_signature:
             if not verify_message(self.auth_key, message):
@@ -44,6 +64,9 @@ class FSMManagingEventHandler(EventHandlerBase):
         return None
 
     def handle_update(self, message):
+        """
+        Does nothing, but triggers an 'fsm_update' message.
+        """
         # pylint: disable=no-self-use
         return message
 

lib/tfw/components/ide_event_handler.py

@@ -157,7 +157,8 @@ class IdeEventHandler(EventHandlerBase, MonitorManagerMixin):
         """
         Read the currently selected file.
 
-        :return dict: message with the contents of the file in data['content']
+        :return dict: TFW message data containing key 'content'
+                      (contents of the selected file)
         """
         try:
             data['content'] = self.filemanager.file_contents