more documentation

script/masterloop.py

@@ -107,7 +107,10 @@ def inform_masterloop_factory(who):
 
 
 def handle_request(r):
-    """Handle a node's request to seize/release control."""
+    """Handle a node's request to seize/release control.
+
+    Update the state if needed.
+    """
     global state
     module = r.module
     message = r.message
@@ -176,6 +179,8 @@ if __name__ == '__main__':
 
     ic = rospy.Service('inform_masterloop', InformMasterloop, handle_request)
 
+    # Necessary initializations all have been performed by now
+
     def _shutdown():
         if speech_in_progress:
             speech.cancel_goal()
@@ -183,7 +188,7 @@ if __name__ == '__main__':
 
     rospy.on_shutdown(_shutdown)
 
-    while not rospy.is_shutdown():
+    while not rospy.is_shutdown():  # Run the speech detection loop
         if state in ('idle', 'imitate', 'dead'):
             if not speech_in_progress:
                 speech_in_progress = True