Reference pages should document function parameter types and default values
- Dominant language
- Java
- Stars
- 14.6k
- Forks
- 7k
- PR merge metrics
- No merged PRs in 30d
Description
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.
Contributor guide
Research direction
Start by reviewing the Arduino function reference pages and the corresponding headers mentioned in the issue. Inventory the declaration formats, parameter types, optional defaults, and overloads, then make the documentation consistent for every affected function and verify that each declaration matches its header.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100