Specify data types in function definitions

[nickgammon]

I suggest that the types of arguments and return values be specified in the documentation. For example instead of:

Syntax

digitalRead(pin)

Parameters

Returns

HIGH or LOW

State the data types, eg.

Syntax

int digitalRead(byte pin)

Parameters

Returns

HIGH or LOW

You shouldn't have to muck around looking in the source just to find if the argument is a byte or an int, or what type the return value is.

Also in this particular case, couldn't "parameters" be explained? eg.

Parameters

pin: The pin number to read from, on the Arduino board. This is probably not the pin number on the actual processor chip.

[per1234]

Although that is a standard way to indicate data type in documentation I think that for the beginners Arduino is intended to be accessible to this may be a bit confusing because they may think they need to include the int and byte in their code. I think it would be more clear to state type separately like this:

Syntax

digitalRead(pin)

Parameters

pin: the number of the digital pin you want to read

• Type: byte

Returns

HIGH or LOW

• Type: int

The digitalRead() reference on arduino.cc actually does specify the type of the pin parameter:

pin: the number of the digital pin you want to read (int)

and I think this is a reasonable way to indicate data type but this is not done consistently in other reference pages and the return type is not specified even on the digitalRead() page. Also the type is incorrect, it should be byte not int.

I'd be happy to submit a pull request with the data type specification on all functions but I'd like to get some input on the best format.

[nickgammon]

Yes, it is a pity the only reference to the type of data is incorrect.

It is also a pity that the example shows int which reinforces the error:

int ledPin = 13; // LED connected to digital pin 13
int inPin = 7;   // pushbutton connected to digital pin 7
int val = 0;     // variable to store the read value

void setup()
{
  pinMode(ledPin, OUTPUT);      // sets the digital pin 13 as output
  pinMode(inPin, INPUT);      // sets the digital pin 7 as input
}

void loop()
{
  val = digitalRead(inPin);   // read the input pin
  digitalWrite(ledPin, val);    // sets the LED to the button's value
}

Your suggested alternative could be OK, although I think you do have to learn something to code. I mean, are you going to explain what the word "type" means? Even if you adopted my original suggestion the example below it (if fixed) would clarify what was meant.

If you adopted the briefer (and more conventional) notation, you could always add a link to a page along the lines of "how to interpret function syntax notation".

[per1234]

I agree 100% about the examples using int instead of byte. I really don't see any benefit to doing that. It just teaches a bad habit and people may assume there is a good reason for it. Well now that the reference is on Github maybe something can be done about it. It would be best to change the examples included with the IDE at the same time so all the examples are consistent. I just checked the pull requests and the old Google Code page and didn't see where anyone has tried this before. Are you aware of any attempts at changing the examples to use the appropriate types in the past(other than forum discussions)? Seems like someone would have tried it already.

I hear what you're saying about the conventional notation but for me Arduino is about removing as many unnecessary somethings that the user has to learn as possible so they can get to the fun part, even if that means the documentation is less concise. My alternative makes the information available without forcing it on the user, they can skim over it and come back later if needed. It is more efficient to just learn things the right way from the start, but if you can get beginners past the initial confusion to the having fun part quickly then they are hooked. After that they will have the determination to figure out the rest. I do think that the reference would benefit from having a link to a general overview at the top of the Variable Types section but not necessary to explain on every reference page..

[nickgammon]

My alternative makes the information available without forcing it on the user, they can skim over it and come back later if needed.

That's fine with me.

Are you aware of any attempts at changing the examples to use the appropriate types in the past(other than forum discussions)?

Not personally.

[sterretje]

I just like to add a vote for Nick's suggestion. When I started with Arduino about 2 years ago I found this a big omission.

[darkain]

This "no data types listed in docs" just bit me in the ass again for the Nth time. The latest was confusion over what the returned type of String.chatAt() is. Does it return a single char, an Arduino String, or a two-byte C-String (character and NULL)? All three of these are plausible based on experience with other libraries in the wild on other platforms. I was able to solve this by looking at example source OUTSIDE of the Arduino documentation. That should never need to be the case for basic functions.

For a quick comparison, PHP is regarded as a very quick to pick up and learn language (the justification for not wanting datatypes listed in these docs), and yet despite PHP being a weak-typed language, they STILL list data types within their documentation to ensure zero confusion at any point with the built in libraries.

[dkovari]

@per1234 Your logic about making it easier for beginners sound good to me.
Although as mentioned by others, it would also be nice to include the type info somewhere else on the documentation page.

As a compromise could another section titled something like "Argument & Return Types" be added below the example code section?
I'm imaging the section would look something like this:

---

Argument & Return Types

1. ret_type1 FUNC_NAME(arg_type1 ARG1)
2. ret_type2 FUNC_NAME(arg_type2 ARG2, arg_type2)

1. Description of FUNC_NAME with syntax 1
2. Description of FUNC_NAME with syntax 2

---

Basically, I'm saying it would be nice to approximate the documentation format used on cppreference.com (example: http://en.cppreference.com/w/cpp/numeric/math/pow)

[SeppPenner]

I would like to make a suggestion here, too.

I would organize the whole section from parameters to returns (See image) like the example shown below:

Parameters

Parameter name	Parameter type	Description	Optional
pin	int	The number of the pin on which you want to read the pulse.
value	int	type of pulse to read: either HIGH or LOW.
timeout	unsigned long	the number of microseconds to wait for the pulse to start; default is one second

Returns

Return type	Description
unsigned long	the length of the pulse (in microseconds) or 0 if no pulse started before the timeout ()

For the Syntax section I personally would use the suggestion from @dkovari, like

Syntax

pulseIn(int pin, int value)

pulseIn(int pin, int value, unsigned long timeout)

Gist for example is here: https://gist.github.com/SeppPenner/2df12e8f7fb058a3651913839998d468

I agree with @per1234 that the data types make it more difficult for beginners to understand. However, that's what the example code at the end of the page is for I would suppose.

[SeppPenner]

Can we poll on this? https://doodle.com/poll/bftecm7d3keh5dcx

[dkovari]

@SeppPenner That is the best version yet. It combines all of the elements we've discussed. I think it would be easy for beginners and helpful for experienced programmers too.

[nickgammon]

@SeppPenner Your suggestion is very good, but also the most work for the documenters to implement, and therefore the least likely to be actually done. My original suggestion of just throwing the data types into the documentation is the easiest to actually do, eg.

Syntax

int digitalRead(byte pin)

[SeppPenner]

@nickgammon That's true. The easiest solution (without having to make a lot of changes) is yours, of course.

[Dygear]

Please, please do this! I think @SeppPenner has the most complete answer, but really ANYTHING would be better than nothing. I'm running thought the documentation and this is extremely painful to figure out without it being in the reference docs.

[EDIT]

It looks like #559 has been merged to fix this, but it's not currently up on the main Arduino Reference website yet. ETA for that?

[SeppPenner]

@per1234 Can you check this, please? I do not see the error in the drone build: https://drone.arduino.cc/arduino/reference-en.

@Dygear I can only tell that it should be done already (At least for the English and the German version of the reference).

[per1234]

Can you check this, please? I do not see the error in the drone build

I don't know the cause of it either, but the documentation was published to arduino.cc and, at least in the translation repository I checked, the automated sync issue was created by ArduinoBot. Maybe it was just a temporary glitch. I seem to remember someone from Arduino saying that can happen when you had inquired about Drone build failures previously.

I can only tell that it should be done already (At least for the English and the German version of the reference).

No, it's not done. Some of the reference pages do document parameter and return types but not all of them. Some of the existing documentation is wrong or incomplete. I would love to go through the entire content of the Arduino Language Reference, and confirm all the existing documentation as well as adding the missing documentation. I prepared the way for this work in #559. Now we at least have a standardized format in place for documenting this information.

[SeppPenner]

Maybe it was just a temporary glitch. I seem to remember someone from Arduino saying that can happen when you had inquired about Drone build failures previously.

I already assumed that, too. You're right, I had the same issue in the German repository, too.

Some of the reference pages do document parameter and return types but not all of them.

Really? I haven't seen some. I need to check this again.

Some of the existing documentation is wrong or incomplete.

Yeah, that might be. I will check this, too.

[per1234]

Really? I haven't seen some.

The very first page I checked:
https://www.arduino.cc/reference/en/language/functions/digital-io/digitalread/
Neither the parameter, nor return type is documented.

Yeah, that might be. I will check this, too.

The tricky thing is they aren't guaranteed to be the same from one core to another. Luckily Arduino is standardizing a good deal of the core API via project chainsaw:
https://github.com/arduino/ArduinoCore-API
That isn't actually in use in any of Arduino's cores other than megaAVR, but it will be eventually so it makes sense to base the documentation on the function signatures contained in repository. arduino/ArduinoCore-API only contains the non-architecture specific core code so there are still more reference pages where the function signatures in each of the official cores would need to checked to ensure the documentation is 100% comprehensive regarding parameter and return types.

There is a good chance other issues with the documentation will be discovered at the same time if the process of checking the reference content against the function signatures in the core code is done carefully.

[Dygear]

@per1234 Ironically, the digitalRead function was the exact one I was looking at.

[leonty]

Hi all,
As a software developer with many years of experience I support the topic starter first proposition. The documentation BADLY lacks of functions signatures in the way that all the c/c++/java etc developers are used to read. I realize that this kind of deviations from the documentation de-facto standards might be better for newbies, but... they are not!
Really, how this variant of signature can be easier if it lacks required semantics and a newbie anyways must read all the article to perceive the required information? Moreover, this forces even an experienced developer to read all the article to find the return type and parameter types while he'd only need a full signature. That really wastes time of any developers not regarding their experience.
I think (as others in the discussion) that the most useful pieces of the documentation for a newbie are examples, not meaningless function signatures without types and parameters. I vote for the topic starter proposition and I'd help with bringing the signatures into the standard form.

[per1234]

@leonty the decision has already been made regarding how the parameter and return types will be documented:
#559
We will not be documenting this information via function signatures in the Arduino Language reference.

[SeppPenner]

@per1234 I'm not sure yet, but can we close this as well? As far as I know, the return types and parameter types have been updated everywhere, haven't they? (At least, I remeber that you did something there and I did a lot of updates in the German repo as well).

[per1234]

@SeppPenner I made the formatting of all the existing parameter and return type documentation to match the standard established by the reference sample page in #559. However, there are still many places in the documentation where parameter or return types are not documented at all and there are also places where the existing documentation is incorrect or incomplete (i.e., doesn't reflect that different types are used from one architecture to another). So although the question of how this information should be documented is settled, the need to add the documentation where missing is still very much in need. I'd like to leave it open so we can continue to use this issue for that purpose, while avoiding spending any more time discussing how to document the information.

[SeppPenner]

However, there are still many places in the documentation where parameter or return types are not documented at all and there are also places where the existing documentation is incorrect or incomplete (i.e., doesn't reflect that different types are used from one architecture to another).

I'd like to leave it open so we can continue to use this issue for that purpose, while avoiding spending any more time discussing how to document the information.

Ah okay, I understand that now :)