numpy / numpy/numpydoc

Support type annotations in `Returns` and `Yields` sections

Open
#356 10 comments 9 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type: Enhancement
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.