Go Down

Topic: Amend CurieIMU documentation (Read 846 times) previous topic - next topic


Apr 23, 2017, 11:24 pm Last Edit: Apr 23, 2017, 11:32 pm by saxbophone
I've been perusing the documentation for the CurieIMU inertial measurement unit on-board the Arduino/Genuino 101 at https://www.arduino.cc/en/Reference/CurieIMUreadMotionSensor.

One thing I noticed that was odd was that the documentation claimed that one can pass int
variables into some of the functions and they will write the measured values to the variables you pass.

I found this very strange as C++ argument calling semantics are pass-by-value normally. The function's prototype as documented is this:

Code: [Select]
CurieImu.readMotionSensor(int ax, int ay, int az, int gx, int gy, int gz)

This is definitely pass-by-value, and if this was in fact the actual code the using this to output the measurements from the sensor would not work.

I then searched around for the source code of the library and found it here: https://github.com/01org/corelibs-arduino101/blob/ee08a03b21d5c141020b328974c2392a8484dfa9/libraries/CurieIMU/src/CurieIMU.h#L193

The actual prototype of the function is this:

Code: [Select]
void readMotionSensor(int& ax, int& ay, int& az, int& gx, int& gy, int& gz);

Now, this of course does work as each argument is of int&, which is a reference data type rather than a normal one.

I would propose that the documentation is updated to reflect this and avoid confusing any novice (or intermediate) C++ programmers.

This is not the only function which uses this technique, many others in the library do and I think (should Arduino accept this proposal), these should be changed as well.


I think the idea is that beginners will be confused by the ampersand and they really only need to understand that after calling the function the variables they passed to it will contain the updated values. I think that's generally reasonable for Arduino's purposes but not in the way they have done it. If you look at the way the standard reference pages are written, for example:
The function usage is documented like this:
EEPROM.write(address, value)
then the parameter types are documented in their descriptions:
address: the location to write to, starting from 0 (int)
With that style of documentation I think it is perfectly acceptable to leave off the ampersand because that is the function usage, not signature. However, the CurieIMU library is trying to do a half-assed function signature and that is not acceptable. If they're going to do that the signature should match the library source, including the return type.


That makes sense, I wondered if that might have been why they omitted the ampersand. As I understand it, it has never been Arduino's goal to fully teach all C++ concepts, just provide information on how to use the subset of it that users need to know to use the Arduino libraries, so a simpler style of documentation will do in that respect.

Thanks for sending that example, I agree with you that changing the documentation style to match that would be a good idea.

Go Up