Documentation should be improved to distinguish between macros and functions!

(deleted)

VinzC:
I now tend to believe it’s a C-like macro.

That’s correct. It’s in hardware/arduino/avr/cores/arduino/Arduino.h:

#define constrain(amt,low,high) ((amt)<(low)?(low):((amt)>(high)?(high):(amt)))

(deleted)

A different (arguably better) choice is to update the macros. A detailed discussion is available here…

VinzC: I think there should be distinct sections: macros and functions

I don't think separate sections are needed because some of the macros can be safely used the same as a function, for example another one in Arduino.h:

#define bitRead(value, bit) (((value) >> (bit)) & 0x01)

There's no need for a beginner to know if that's a macro or a function. The reference needs to be accessible to someone who is just plugging in their Arduino for the first time and has almost no programming experience, breaking things into macros and functions just adds another layer of confusion. However, I do think that the reference should try to note any limitations such as the one you have encountered with macros and functions. That one would be very confusing to a beginner and many of the macros will cause this problem. The introduction to each reference page needs to be simple and short but after that should provide as much information as necessary(including data types). This way the user can get the basic description quickly and then if they run into problems come back for the details.

VinzC: having to consult the header files in order to raise the online documentation ambiguities is counter-intuitive and should be avoided, especially if no one knows where ambiguity lies...

I completely agree with that. Just finding the right source file is going to be fairly difficult for a beginner.

(deleted)

I agree with VinzC completely. I recently had a very hard time with digitalRead() and a scenario when i tried to read voltage and average from a current sense resistor while the PWM pin was active, NOT KNOWING that digitalRead() will disable PWM on the pin i was simply trying to enable a sampling for loop that should have worked just fine BECAUSE THIS CAVEAT WAS NOT EVEN MENTIONED ON THE LANGUAGE REFERENCE while i was REFERENCING the digitalRead() function within the OFFICIAL reference. There should be a major edit to the reference for those who want to dig deeper than just blinking an LED or running the demo's.

Caveats should be listed lower on the function pages along with what type the function/macro is, clock cycles for noobs that should maybe be coding certain loops in assembly or using bit shifts instead of divide macro/function, whatever it is to speed up execution time.

Reference should have two distinct sections, one for noobs to arduino who can safely get by blinking a few LEDs & enjoying the experience of easing into programming in C, & another section for more advanced users who may not be aware of things and facts like divide is emulated with a 40 or so line function/macro (i don't know the ramifications of either to my program).

Spending DAYS googling for forum posts on an explanation of why functions work counter intuitively or seem back asswards (see: MIN(), MAX() in reference) when all this confusion and delay could be avoided by givinga bit more NEEDED info right in the reference. Noobs will gloss over more comple things in the refereence and focus on the details in which they were there in the reference for. You, the developers of arduino have made a transistion from digital gates to programming on MCU's very easy indeed. But YOU telling me "this is all you need to know about this "function" and dont worry about the caveats like execution time or things like divide is emulated or that digitalRead() disables the PWM pin i'm trying to read just leads to frustration, MORE confusion, and delays. Most would not be turned away from Arduino as they do with their brilliant ideas simply because their programs SHOULD work according to the REFERENCE, but do not because they are macros and not functions!

I think the root of the problems is that the majority of users refuse to read the datasheet of microcontroller used.

The datasheet of AVR clearly indicates that the timers can take control of some pins [u]and not just for[/u] [u]the[/u] [u]PWM[/u]. When it is the timer that controls a pin it is obvious that we can no longer use this pin "classically" without stoping the timer.

Regrettably Arduino has not laid down rules for the documentation of libraries. For example Arduino would have itself used and demanded that all the libraries are documented with Doxigen, users would do less error due to ignorance.

The past is the past but there is still time to impose rules for new libraries or for updates. If Arduino would actually work hand in hand with the community, Arduino should organize a poll on this it would be good to include in the documentation of libraries.