Missing information and potential improvements in Reference

I'm a brand new newbie to Arduino, but I have a pretty good background with programming (not so much electronics/wiring). I've spent the day going over some of the built-in examples and using the reference to make sure I understand everything going on. I've found a few things missing:

• Constants
  The Constants reference page lists a few of the constants, but definitely not all of them. For examples, the constants DEFAULT, INTERNAL, and related others listed in analogReference's reference page. There's also A0, A1, etc. which define analog pins - those aren't listed either, and aren't even mentioned in analogRead.
  In addition, I think it would be nice - albeit not too crucial - to list the actual integer value of each constant. All constants of each group can be put in a table with one column for the name (e.g. LOW), one for the decimal value (e.g. 0), and one for description (e.g. "The input is low (below tolerance) or the output should be set low (0v).") I am "stealing" this idea/design directly from how the Garry's Mod Wiki documents enums (which are implemented in Lua via simple global variables, treated as if they were constants). I think this table format is very easy to read and work with - some adaptation of it would be nice for the Arduino reference.
• Missing syntax reference - the ?: operator is not mentioned in the Reference. I don't know if there's anything else missing, that's the one thing I came across. A quick google search shows that this is a fairly common source of confusion for Arduino developers who come across it in someone else's code, so putting it under Reference is sure to help.

I'm used to a wiki for reference, as the aforementioned Garry's Mod wiki and even the Mozilla Developer Network JavaScript Reference - reference that anyone can edit is very powerful and demonstrably successful. It's a shame that Arduino didn't adopt the same principles, so I'm forced to just write about it here - I hope this gets something done!

NeatNit:
The Constants reference page lists a few of the constants, but definitely not all of them. For examples, the constants DEFAULT, INTERNAL, and related others listed in analogReference's reference page.

Those constants are very specific to that function and rarely used. The Arduino documentation focuses on being accessible to beginners which means not providing an overwhelming amount of information so I think it makes more sense to only mention the frequently used constants on that page. Maybe a note that it's not a complete list would make sense.

NeatNit:
There's also A0, A1, etc. which define analog pins - those aren't listed either, and aren't even mentioned in analogRead.

Now those are frequently used constants and it's surprising they aren't mentioned on either page.

NeatNit:
list the actual integer value of each constant. All constants of each group can be put in a table with one column for the name (e.g. LOW), one for the decimal value (e.g. 0)

The whole point of constants is that you don't need to know the value. I can't think of how that would be useful other than for people to use the information to write bad code that relies on those constants having specific values. This is a bad idea because there are many different platforms and some might use those constants in different ways.

NeatNit:

• Missing syntax reference - the ?: operator is not mentioned in the Reference.
  [/quote]
  The Arduino reference page is not intended to be a comprehensive C++ language reference. There are many of those already that do an excellent job of it. The Arduino reference page is mostly focused on documenting the API of the Arduino core libraries with a small amount of the most basic programming concepts thrown in. I do think it would make sense to add a note that many other C++ functions exist with a link to a full C++ reference. In fact it already does this for avr-libc but I don't think it's well explained and I don't think that's the best reference.

NeatNit:
I'm used to a wiki for reference

I'm somewhat in agreement but I also see that there are many people like you who don't fully understand the intention behind the reference page and would make it less beginner friendly. A couple years ago they actually set up a system to make it very easy for anyone to submit proposals for changes to the pages but never made the final effort to actually use the thing, really sad. However, You can submit corrections or suggestions for improvements here:
Issues · arduino/Arduino · GitHub
I've found that if you take the time to clearly explain the issue and provided complete text for the suggested edit (rather than just a vague recommendation) they usually will take action very quickly. The person in charge of these edits, agdl, is very easy to work with. I have successfully gotten many problems fixed with the reference pages via that approach.

I should note that we do have a publicly editable wiki:
http://playground.arduino.cc/
and you are welcome to add any content you like there or make corrections or improvements to the existing content.

pert:
Those constants are very specific to that function and rarely used. The Arduino documentation focuses on being accessible to beginners which means not providing an overwhelming amount of information so I think it makes more sense to only mention the frequently used constants on that page. Maybe a note that it's not a complete list would make sense.

A note would probably help, something like: "These are only the most commonly used constants. Some functions have their own set of constants, which are listed in their respective pages."

pert:
Now those are frequently used constants and it's surprising they aren't mentioned on either page.

Right?

pert:
The whole point of constants is that you don't need to know the value. I can't think of how that would be useful other than for people to use the information to write bad code that relies on those constants having specific values. This is a bad idea because there are many different platforms and some might use those constants in different ways.

That I completely agree with, I don't remember why I even brought it up. There is one case where it would be useful - to use digitalRead (or another function like it) as-is inside an if condition, which you should only do if you are guaranteed that LOW is 0 and HIGH is non-0. But yeah, it's probably better to hide the values for the sake of better code.

pert:
The Arduino reference page is not intended to be a comprehensive C++ language reference. There are many of those already that do an excellent job of it. The Arduino reference page is mostly focused on documenting the API of the Arduino core libraries with a small amount of the most basic programming concepts thrown in. I do think it would make sense to add a note that many other C++ functions exist with a link to a full C++ reference. In fact it already does this for avr-libc but I don't think it's well explained and I don't think that's the best reference.

Yeah, I briefly saw that link but assumed it would be documentation for some library rather than the language. Worth noting, though, is that nowhere is it stated unambiguously that the Arduino language is C++. The bottom of the reference home page says: "The Arduino language is based on C/C++". "Based on" implies that it's not 1:1 - meaning that Arduino may not have all C/C++ features, and it may deviate from their established rules and conventions (e.g. using setup() and loop() instead of just main()). Also, C/C++ is ambiguous in itself - where there's a difference, is it C or is it C++? For the non-beginner programmer, this is an important line to define.

pert:
I'm somewhat in agreement but I also see that there are many people like you who don't fully understand the intention behind the reference page and would make it less beginner friendly.

I can't speak for anyone else, but I would never make a significant change before I've had a lot of experience in the wiki and completely understand its design, the reasons behind it, and so on. Also, all wikis have a style guide, with dos and don'ts, so you can preface the guide with e.g. "The primary goal of this reference is to be beginner-friendly. Always keep this goal in mind when making edits". Bad edits would be easily reverted or improved by the more experienced editors. I don't think this risk is too relevant, given that there are enough real-world examples of wikis done right.

pert:
A couple years ago they actually set up a system to make it very easy for anyone to submit proposals for changes to the pages but never made the final effort to actually use the thing, really sad.

pert:
However, You can submit corrections or suggestions for improvements here:
Issues · arduino/Arduino · GitHub
I've found that if you take the time to clearly explain the issue and provided complete text for the suggested edit (rather than just a vague recommendation) they usually will take action very quickly. The person in charge of these edits, agdl, is very easy to work with. I have successfully gotten many problems fixed with the reference pages via that approach.

All reference pages say this at the bottom:

Corrections, suggestions, and new documentation should be posted to the Forum.

If there's a better way, it should replace the forum link.

pert:
I should note that we do have a publicly editable wiki:
http://playground.arduino.cc/
and you are welcome to add any content you like there or make corrections or improvements to the existing content.

Thanks for the link, I'll take a look around there for sure. But I really was talking specifically about the Reference section.

NeatNit:
All reference pages say this at the bottom:If there's a better way, it should replace the forum link.

Yeah, it's unfortunate they tell people that because nobody from Arduino ever reads this forum section. I see they actually have changed the Contact Us page to say:

If you have found an error in the online documentation, please check if it's already known by looking at the github documentation issues, and if it's not known, please add it to the list.

So that change should probably be made throughout the site. Basically the way the system works now is that the forum members look over any suggestions. If there's something obvious that I can reproduce and I feel knowledgeable enough about I'll go ahead and submit an issue for it. If it seems like it might be valid but I'm not in a position to effectively submit an issue I'll post a link to the issue tracker. So it kind of works and this does provide a filter of volunteers before the developers spend their valuable time dealing with it but I'm sure there are lots of valid suggestions gathering dust many pages deep in this forum section. I know I have a bunch of them on my "to do" list that I haven't found time for.

NeatNit's issue report:

I have an Uno and the constant A0 has the value 14. The example AnalogReadSerial uses this constant to read the value: int sensorValue = analogRead(A0);
However, the analogRead reference page says:

pin: the number of the analog input pin to read from (0 to 5 on most boards, 0 to 7 on the Mini and Nano, 0 to 15 on the Mega)

So which is it? Is the reference page plain wrong, or are A0 and 0 equivalent for analogRead?

They're both right. analogRead(0), analogRead(A0), and analogRead(14) all will read from the same pin. Here's how that happens:

	if (pin >= 14) pin -= 14; // allow for channel or pin numbers

This is very confusing because you would expect all the pinout configuration to be contained in pins_arduino.h but for some reason they hardcoded pinout assumptions into analogRead().