more documentation

script/calibrator.py

@@ -1,5 +1,9 @@
 #! /usr/bin/env python
-"""The script for calibrating the arm lengths and 'joystick' extents."""
+"""The script for calibrating the arm lengths and 'joystick' extents.
+
+You will normally not call this script directly but rather with
+`roslaunch teleoperation calibration.launch`
+"""
 
 import os
 import json
@@ -14,7 +18,23 @@ from teleoperation.msg import RequestSpeechAction, RequestSpeechGoal
 
 
 def calib_field(sentences, src_frames, targ_frames):
-    """Retrieve a relative transform of some marker."""
+    """Retrieve a relative transform of some marker.
+
+    Parameters
+    ----------
+
+    sentences : list of str
+        What to say.
+    src_frames : list of str
+        The names of tf source frames (from where to transform)
+    targ_frames : list of str
+        The names of tf target frames (to where to transform)
+
+    Returns
+    -------
+    list of transforms
+
+    """
     ok = False
     t_and_q = []