Oh no, don't bring ARMs into the discussion as well.messed my cortex.
Well that's true, I was expecting a Due but no showor did Santa not bring you what you asked for this year?
Of course code is good but it's not "documentation". One of my gripes with Arduino is that to find out what exactly "pin 17" is connected to I have to pull out the schematics and/or delve into the bowels of the core libraries and their associated lookup tables.Documentation is verbose... including the SOURCE CODE for the entire Arduino family.
For example AFAIK there are no official pinout drawing for Arduinos. In an attempt to help I created this for the new Due.
IMO this sort of thing should be done by the Arduino team. OTOH maybe that's the point of open source and having a supporting community.
Another example from the official reference section
No mention of return data type, you have to look at some code. Another exampleread()
Description
Reads incoming serial data. read() inherits from the Stream utility class.
Syntax
Serial.read()
WTF data types are val, str, buf and len?write()
Description
Writes binary data to the serial port. This data is sent as a byte or series of bytes; to send the characters representing the digits of a number use the print() function instead.
Syntax
Serial.write(val)
Serial.write(str)
Serial.write(buf, len)
Just below that you have some explanation
str: a string to send as a series of bytes -- technically it is not a "string", it's an array of char (or maybe bytes) with a NULL termination.val: a value to send as a single byte
str: a string to send as a series of bytes
buf: an array to send as a series of bytes
len: the length of the buffer
buf: an array to send as a series of bytes -- an array of what?
len: the length of the buffer -- is this a uint8, int, long, long long.
To be fair as this is C++ maybe the functions are overloaded to handle all possibilities, but I shouldn't have to trawl the source code to find out.
And although they do say to use the print() function to send characters I doubt a beginner will understand the implications and there's no mention of why code like
x = 5;
Serial.write (x);
Doesn't show anything on a terminal. That will stump a beginner for days. (Hint, 5 is not an ASCII printable character)
OK, rant over Sorry, I'm a bit of a documentation freak.