DOCUMENT IT

script/masterloop.py

@@ -1,4 +1,6 @@
 #! /usr/bin/env python
+"""The master state machine node."""
+
 import os
 from argparse import ArgumentParser
 
@@ -37,6 +39,7 @@ mp = ALProxy('ALMotion', os.environ['NAO_IP'], 9559)
 
 
 def init_voc_state_speech():
+    """Initialize the transitions."""
     global VOC_STATE, SPEECH_TRANSITIONS
     VOC_STATE = {
         'idle': [KILL] + ([IMITATE] if not AI else []),
@@ -55,6 +58,7 @@ def init_voc_state_speech():
 
 
 def hands(what):
+    """Handle the command to do something with the hands."""
     try:
         _hands = rospy.ServiceProxy('hands', Hands)
         newstate =  _hands(what).newstate
@@ -64,6 +68,7 @@ def hands(what):
 
 
 def speech_done_cb(_, result):
+    """Handle the recognized command."""
     global speech_in_progress, state, hand_state
     _state_old = state
     rospy.loginfo('SPEECH: {}'.format(result))
@@ -83,6 +88,12 @@ def speech_done_cb(_, result):
 
 
 def inform_masterloop_factory(who):
+    """Create a function to inform the masterloop.
+
+    Every node infroms the master, so it's nice to have a factory for
+    these functions.
+
+    """
     def inform_masterloop(what):
         try:
             inform_masterloop = rospy.ServiceProxy('inform_masterloop',
@@ -96,6 +107,7 @@ def inform_masterloop_factory(who):
 
 
 def handle_request(r):
+    """Handle a node's request to seize/release control."""
     global state
     module = r.module
     message = r.message
@@ -184,4 +196,4 @@ if __name__ == '__main__':
                 speech.cancel_goal()
                 speech_in_progress = False
 
-        rospy.Rate(10).sleep()
+        rospy.Rate(10).sleep()  # Run at 10 Hz or something