Normally, when I read documentation, I expect it to include data types in every declaration. The Arduino documentation is very inconsistent about this, with some functions containing no declaration at all, some containing a declaration without types, some containing types as part of the text description for parameters, etc. This should really be cleaned up when someone has the time.

Additionally, functions that have multiple variants with optional parameters need to specify what the default value is.

Example: random(min, max) and random(max). One would assume that the declaration is

long random(long min = 0, long max)

but it could just as easily be an overloaded function

long random(long max)
long random(long min, long max)

where the first one uses -max as min.

Including the complete declarations in every function's documentation would go a long way towards clarifying their usage without requiring people to dig through the headers.