For properties and method parameters that accept multiple types, documentation should promote the recommended type
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 128
- Forks
- 110
- Avg merge
- 5d 14h
- Merged PRs (30d)
- 10
Description
Description of issue
The main idea being documentation should guide the users to use the most-pythonic type for any property or method parameter. e.g.:
https://github.com/ni/nimi-python/blob/8540e86f00dc4b7aa9dbf5d905275db7255d9c7b/generated/nidigital/nidigital/session.py#L607
documentation says:
offsets (list of float in seconds or datetime.timedelta):
In this case, documentation should mention that datetime.timedelta is the recommended type, as that the pythonic way of representing time intervals.
Another instance would be the documentation for repeated capabilities:
Repeated capabilities attributes use the indexing operator [] to indicate the repeated capabilities. The parameter can be a string, list, tuple, or slice (range). Each element of those can be a string or an integer. If it is a string, you can indicate a range using the same format as the driver: ‘0-2’ or ‘0:2’
I think it's still valuable to document all the different types that can be passed in, for cases where the recommended type cannot be used; but there should be a clear distinction between recommended type and the others.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the generated nidigital/session.py example linked in the issue, especially the offsets documentation. Trace how documentation for multi-type properties and method parameters is generated, then identify how recommended and fallback types should be distinguished. Done means affected documentation consistently promotes the most-pythonic type while still listing supported alternatives.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100