Ambiguous native function descriptions

[ypiguet-epfl]

In the function descriptions in aseba/native.c, the role of arguments isn't always stated clearly. For instance for math.add, the description reads adds src1 and src2 to dest, element by element while the element-wise sum of src1 and src2 is stored into dest, not added to dest.

Suggestion: revise all native function descriptions, and store them in programming documentation, neither in the vm nor elsewhere in the robot firmware.

[mbonani]

The description in the vm are small reminder to have them dynamically listed. A more detail description is in the help of the asebastudio. It is also now in https://github.com/aseba-community/aseba/blob/master/docs/en/aseba-std-natives.rst that could be included in helps of different programms.
I agree that the vm description is perhaps ambiguous but it has to be short.

[mbonani]

I just read the function description display in studio. I just found math.add that is not crystal clear:
"adds src1 and src2 to dest, element by element" -> probably the function should been have called math.sum.
There is two possibilities:

• we change the name to math.sum, but it could break users code
• we change only the description to "adds src1 and src2, store to dest, element by element"

[stephanemagnenat]

Sum is a bad name here because it is commonly assumed to mean "sum all elements together". What about: "adds src1 and src2, write to dest, element by element"

[mbonani]

for me it's ok