Remarks on the documentation

[c-joly]

Hi @costashatz, here are some comments about the documentation, linked to my review on JOSS https://github.com/openjournals/joss-reviews/issues/6771

In my opinion, the API documentation is not enough. It looks to be limited to the automatic generation of the C++ API but without more comment. Moreover, there is no API doc of the Python version. Ideally, a complete documentation inside the source code should be added (e.g. Python Doctoring, doxygen). However, the FAQ provides some very useful examples that can help for most cases. Thus, I do not ask a complete API documentation to validate the JOSS review, but at least to complete some examples with more comments. Some examples files were sometimes difficult to understand directly. Here are some examples taken from the Python samples:

Examples in pendulum.py:

• In the following code:

  Ctrl  [0.0]
  # @SIMPLE_CONTROL_PYTHON@
  controller1 = rd.SimpleControl(ctrl)
  robot.add_controller(controller1)
  # @SIMPLE_CONTROL_PYTHON_END@
  ctrl = [-1.0]
  controller2 = rd.SimpleControl(ctrl)
  robot.add_controller(controller2, 5.)
  

  • What is the second argument of add_controller in the second call of the function?
  • I do not understand well which controller is called when we add several controllers like in this example? In the following part of the example, controller1 is changed, not controller2…
  • I see here one kind of controller. I guess it is a direct value in the unit of the joint type (torque, velocity...). In some other examples, I saw PD controller. What kind of other controllers are available by default (it looks like PID is not available)?
• simu = rd.RobotDARTSimu(): what is the default simulation step? (Maybe I missed it in the FAQ?)

•  print((robot.body_pose("pendulum_link_1").multiply(size)).transpose())
  

  According to my understanding, robot.body_pose("pendulum_link_1") gives the transformation matrix of the "beginning" of the pendulum and we need to multiply it by a vector representing the the coordinates of the end of the pendulum in that frame in order to have the coordinates of the end of the pendulum in the world frame. This is not completely obvious and adding a few comments in the code to explain the role and type of each matrix can be useful.
• robot.reset(): what does exactly the reset function? And what is the purpose of calling it at the end of the script (what happens if we don’t do it?)

Example in example_parallel.py

• What is the goal of rd.gui.run_with_gl_context? Actually, I did not succeed to make it run on my Mac and I directly called the test function in this example (see #208)

Example in HelloWorld.py

• robot.set_base_pose([0., 0., 0., 0., 0., 0.2]): what are the first 6 values of the vector? I guess the 3 last ones are the x, yand z coordinate (because of the 0.2!), and that the 3 first ones represent the orientation of the robot frame. But with which convention? Are they precession, nutation and intrinsic rotation angles; or maybe yaw,pitch,roll?...

Example in cameras.py

• simu.add_checkerboard_floor(10.): can you explain what is the goal of the argument (in all the other examples, the function is called without argument).

These are some examples, there are other lines of code in the examples that are not obvious to understand and that do not come with a comment. On the other hand, some files are very well commented like robot_properties.py which is very helpful to understand how to personalize a robot. Can you review the different C++ and Python examples and add comments to the lines that may be difficult to understand directly?