arduino / arduino/Arduino

Reference pages should document function parameter types and default values

Open
#4,706 1 comment 3 reactions 0 assignees View on GitHub
Component: Documentation Library: Other Type: Bug
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.