Units and range in documentation

[ghost]

From @fabienrohrer on January 19, 2016 8:36

Units and range in documentation are heterogenous, and sometimes missing.

Related forum messages:
https://www.cyberbotics.com/forum?message=5836
https://www.cyberbotics.com/forum?message=1339
https://www.cyberbotics.com/forum?message=2361

Copied from original issue: omichel/webots#3414

[ghost]

From @fabienrohrer on January 19, 2016 8:36

About fields, the reference manual follows more or less this rule:

NodeName {
  VRMLType fieldName defaultValues # [\[\(]minRange,maxRange[\]\)], (units)
}

All of the case can be seen here:
https://www.cyberbotics.com/reference/contactproperties.php

➡️ I would propose to homogenize this.

Some of them are showing a small label explaining the field:
https://www.cyberbotics.com/reference/accelerometer.php
But this seems redundant with the description bellow.

➡️ I would propose to drop this description label.

This is redundant also with the comments here:
https://github.com/omichel/webots/blob/master/resources/nodes/

➡️ I would propose to remove all the comments here.

About function units, it is generally described in the comments.
For example, the return of the [m/s^2] of the Accelerometer's wb_accelerometer_get_values() function.

➡️ I would propose to describe the units of the function into the function description.

[ghost]

From @fabienrohrer on January 19, 2016 8:37

If everyone agree, I can begin this refactoring.

[ghost]

From @omichel on January 19, 2016 8:45

I wouldn't drop the comments from the *.wrl files as they are useful when you look at these files to understand the nodes without having to go to the reference manual.

[ghost]

From @omichel on January 19, 2016 8:49

Maybe you address a single node for now and post the results here for review, so that we can agree if this is the right way to do.

[ghost]

From @fabienrohrer on January 19, 2016 8:52

I wouldn't drop the comments from the *.wrl files as they are useful when you look at these files to understand the nodes without having to go to the reference manual.

Maintaining duplicate data should be avoided in every case. The proof of this is that this directory is currently completely unsynchronized from the reference manual.
The users are not interesting in seeing this directory.
The argument about our convenience seems weak against the data duplication in my point of view.

Maybe you address a single node for now and post the results here for review, so that we can agree if this is the right way to do.

Good idea. I will try to find a node with all the issues.

[ghost]

From @stefaniapedrazzi on January 19, 2016 8:59

Personally I think it is very useful for us to have comments in the WRL files and we should keep them.
Then, I'm not sure to understand where you want to add the units description in the reference manual but I like the form:

NodeName {
  VRMLType fieldName defaultValues # [\[\(]minRange,maxRange[\]\)], (units)
}

as it is immediately visible without having to search into the text.

[ghost]

From @fabienrohrer on January 19, 2016 9:21

I'm strictly convinced that duplicating data should be avoided in this case.
https://en.wikipedia.org/wiki/Don%27t_repeat_yourself

[ghost]

From @stefaniapedrazzi on January 19, 2016 9:27

Where do you mean we are duplicating the data?

[ghost]

From @fabienrohrer on January 19, 2016 9:30

The comments of the nodes description in the reference manual, and the comments in the *wrl files. They are currently half copy-pasted.

[ghost]

From @stefaniapedrazzi on January 19, 2016 9:41

It seems that in the reference manual we only show the range and the units and not the other comments.
Personally I'm not sure if I would consider this as documentation of the field or duplication of the code in WRL.

[DavidMansolino]

Fixed #600

[fabienrohrer]

Range documentation have been solved in https://github.com/omichel/webots-doc/pull/600/files but units are still under-documented. A user just reported this again.

[omichel]

I will fix the issues reported by this user: missing units for wb_motor_set/get_available_force() and LinearMotor.maxForce and I will check other similar units with RotationalMotor and torque.