Support type annotations in `Returns` and `Yields` sections
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 355
- Forks
- 181
- Avg merge
- 1d 9h
- Merged PRs (30d)
- 3
Description
Currently, when using numpydoc-style docstrings alongside Python type annotation, the types of returns or yields must be specified twice, which is tedious and also error prone. I would like to propose a backward-compatible addition to the docstring specification, which allows returns/yields to be specified without return types:
Returns
-------
return1_name :
Description of `return1_name`.
return2_name :
Description of `return2_name`.
Note the addition of the colons to distinguish return names and return types in a backward-compatible way.
Additionally, for a single return value with a Python return type annotation, it would be great if the following would be possible:
Returns
-------
Description of the return
or
Returns
-------
Description of the return
The same suggestions should also work for the Yields section
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
Begin with the Returns and Yields docstring parsing behavior and the examples in this issue. Determine how existing typed forms can be distinguished from colon-only and description-only forms, then verify backward compatibility for both sections.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100