Documentation: please mention the type of return functions.

[rin67630]

The documentation of Functions should IMHO at least mention the type of the returned parameter(s).

E.g: https://www.arduino.cc/reference/en/language/variables/data-types/string/functions/length/

Returns

The length of the String in characters.

As what?
Integer, Byte, unsigned Integer?

Why isn't that mentioned?

How do you react on that error using the Arduino documentation?

error: format '%u' expects a matching 'unsigned int' argument [-Werror=format=]
         Console2.printf("\nTry conn' to %s (%u) , %s (%u) \n", ssid.c_str(), ssid.length(), pass.c_str()), pass.length();

Thank you for considering my request for the benefit of everybody.

[rin67630]

P.S. I have found my error in the preceding example, it was a misplaced parenthesis, not a type problem.

Nevertheless the request remains: please always indicate the type of the returned parameters in the documentation.

[mahendra1290]

hi @per1234 Can I help into this?

[kengdahl]

So I asked about this and this is one answer I got:

So the c++ function strlen() returns the value as an unsigned int , so I would make a guess that it is the same.

Does this make sense?

[per1234]

@kengdahl there is no need to guess. Just consult the source code.

In this case, it is here:
https://github.com/arduino/ArduinoCore-API/blob/1.3.1/api/String.h#L94
and here:
https://github.com/arduino/ArduinoCore-avr/blob/1.8.4/cores/arduino/WString.h#L81
(the Arduino AVR Boards platform does not use ArduinoCore-API, so it is necessary to check its bundled core library)

[kengdahl]

Ok.

Then I'm going to change it to say:
"The length of the String in characters as an unsigned int."

[kengdahl]

This should be fixed now.

It now says:
The length of the String in characters. Data type: unsigned int.

[per1234]

@kengdahl it is not fixed. The "e.g." meant that this was only one example of the many places where the Arduino reference pages do not document the return type of a function.

There must be a comprehensive review of all Arduino Language Reference and Library Reference content and the return type documented everywhere in order to resolve this deficiency.

We already have a dedicated issue for doing that in the Arduino Language Reference: arduino/reference-en#15 so we can consider this issue to be exclusively for the library reference content. Since that content is spread out across many repositories, this issue tracker (which serves as a bit of a "catch-all" in addition to being for the Arduino IDE 1.x code base) is a reasonable place to store the issue.

[kengdahl]

@per1234 Sorry. I misunderstood this. Good that you opened it again.

[per1234]

I see we have another report about this at #4706.

It is best to have only a single issue per subject so we can consolidate all relevant discussion to one place, so I'll go ahead and close this in favor of the other.

If you end up with additional information to share, feel free to comment in the other thread.