Docstrings use `Optional[T]` incorrectly
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 592
- Forks
- 199
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 10
Description
Many of this package's docstrings incorrectly conflate Optional[T] with default arguments.
typing.Optional[T] means "either a T or a None", which is orthogonal to whether the parameter has a default argument or not.
Example: https://github.com/ni/nidaqmx-python/blob/master/src/handwritten/task.py
def __init__(self, new_task_name='', *, grpc_options=None):
"""
Creates a DAQmx task.
Args:
new_task_name (Optional[str]): Specifies the name to assign to
the task.
If you use this method in a loop and specify a name for the
task, you must use the DAQmx Clear Task method within the loop
after you are finished with the task. Otherwise, NI-DAQmx
attempts to create multiple tasks with the same name, which
results in an error.
grpc_options (Optional[:class:`~nidaqmx.GrpcSessionOptions`]): Specifies
the gRPC session options.
"""
new_task_name (Optional[str])): ... means that new_task_name has a type of typing.Optional[str], but that is not the case. It has a type of str. If you do not specify an argument for new_task_name, the default argument is used, which also has a type of str.
grpc_options (Optional[:class:~nidaqmx.GrpcSessionOptions]): ... is correct. The default argument has type None, so typing.Optional[GrpcSessionOptions] is needed to accept either a GrpcSessionOptions or a None.
https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html uses the syntax param2 (:obj:int, optional): . I don't know which meaning of "optional" it's using.
The best way to fix this is to add type hints and delete the types from the docstrings.
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 docstring example in src/handwritten/task.py and read the linked issue #209 about adding type hints. Audit the package docstrings for cases where Optional describes a default rather than a nullable type, then align the documentation with the actual parameter types. Done means the incorrect Optional annotations are corrected consistently.
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