Mark, thanks for accepting my other change. I have a few more suggestions. I looked at a lot of documentation style guides. They are pretty much universal in using:
Arguments separated by the '|' ( ) bar notation are mutually-exclusive.
Arguments or option-arguments enclosed in the '[' and ']' notation are optional and can be omitted.
To indicate required arguments, Angled brackets ‘<...>’ are commonly used, following the same grouping conventions as square brackets. (You actually use this in your function example).
See the following for reference:
IEEE standard: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
Google: https://developers.google.com/style/code-syntax
Wikipedia: https://en.wikipedia.org/wiki/Usage_message
Doxygen: https://www.doxygen.nl/manual/commands.html
- Based on the above, I propose you use the following:
attach(pin, [<min_uS>, <max_uS>])
pinMode(pin, <INPUT | OUTPUT | INPUT_PULLUP>)
digitalWrite(pin, <HIGH | LOW>)
analogReference(<DEFAULT | INTERNAL | EXTERNAL>)
shiftOut(dataPin, clockPin, <MSBFIRST | LSBFIRST>, value)
attachInterrupt(interrupt, func, <LOW | CHANGE | RISING | FALLING>)
I also propose you use:
tone(pin, freq_Hz, [duration_ms])
and eliminate:
tone(pin, freq_Hz)
which might give you enough room to squeeze in:
byte shiftIn(dataPin, clockPin, <MSBFIRST | LSBFIRST>)
for completeness.
- You show the pulseIn() function. In looking at the Arduino Language Reference page, it seems like pulseInLong() has replaced it. It says, “pulseInLong() is an alternative to pulseIn() which is better at handling long pulse and interrupt affected scenarios.”
I propose you replace:
unsigned long pulseIn(pin, [HIGH, LOW])
with:
unsigned long pulseInLong(pin, <HIGH | LOW>, [timeout])
-
If you have enough space, I would document that “value” ranges from 0...255 in:
analogWrite(pin, value)
-
I pound on my students to use bytes to declare pins on the Arduino since you want to save RAM space and there are less than 256 pins on any Arduino. You have an example on your sheet:
int myPins[] = {2, 4, 8, 3, 6};
I propose you use:
byte myPins[] = {2, 4, 8, 3, 6};
Just think, this one example on your sheet might get some people to start writing better Arduino code!
-
This suggestion I can live without since you would have to chop something out and that might be difficult (I’d suggest the Servo library since it’s the only one you show that’s not physically attached to the Arduino). My suggestion is to add the following from the Arduino Language Reference page for completeness:
isAlpha()
isAlphaNumeric()
isAscii()
isControl()
isDigit()
isGraph()
isHexadecimalDigit()
isLowerCase()
isPrintable()
isPunct()
isSpace()
isUpperCase()
isWhitespace()
Thanks for listening and thanks again for such a great reference sheet!