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)