# Revised Numpydoc guidelines for Parameters, Returns & Yields sections

XMLWordPrintable

## Details

• Type: RFC
• Status: Implemented
• Resolution: Done
• Component/s:
• Labels:
None

## Description

This RFC concerns updated guidelines around the documentation of Parameters, Returns, and Yields sections with Numpydoc. These guidelines reflect issues that the team has encountered while implementing Numpydoc.

The implementation ticket is DM-16827 (see PR).

## Proposal A: Definition list formatting for Struct types

For Struct types (and dict types with known keys), I'm proposing that we document individual attributes/keys using a definition list syntax, rather than the list syntax that was previously recommended. Definition lists are more semantically appropriate.

See draft documentation.

## Proposal B: Specific guidelines for handling *args and **kwargs

This RFC also introduces guidelines on how to document ***args
and * *{{kwargs}} parameters, which are largely absent from the current guidelines. The choice to name the parameters *args and ** *kwargs rather than args and kwargs comes from reviewing existing practice. (I know I've told some people to use kwargs, sorry about that.)

See draft documentation

## Proposal C: Improved documentation for dict types

See draft documentation

My recommendation is to write a dict-type parameter like this:

 measurements : dict  Measurements of metrics. The keys are names of metrics (str), and  values are astropy.quantity.Quantity instances, which combine  both value and unit information. 

That is, just write dict as the type and describe keys and values in the description.

### C: Alternative 1

An alternative that Krzysztof Findeisen has shown in practice is to put the full type information in the type field:

 measurements : dict from str to astropy.quantity.Quantity  Measurements of metrics. 

C: Alternative 2

Another variation with different formatting might be:

 measurements : dict (str: astropy.quantity.Quantity)  Measurements of metrics. 

I'm opening to these alternatives if they're popular.

## Proposal D: Specific recommendation on naming return variables

Lastly, I propose adding text recommending against unnamed return variables. See draft documentation

For example:

 def sayHi():  """Say hello.    Returns  -------  str  A greeting.  """  returns "Hello world" 

The problem with this usage pattern is that str doesn't get linked; it's displayed as the name of the returned variable.

## Activity

Hide
Russell Owen added a comment -

I would be equally happy with colon or comma. I don't understand the Sphinx prior art well enough to have an opinion, other than please either require parenthesis or square brackets in our coding standard, don't allow a mix.

Show
Russell Owen added a comment - I would be equally happy with colon or comma. I don't understand the Sphinx prior art well enough to have an opinion, other than please either require parenthesis or square brackets in our coding standard, don't allow a mix.
Hide
Russell Owen added a comment -

Tim Jenness this is a bit of distraction but...do you anticipate using type annotations everywhere or only in select places? I haven't used it much yet. At one level it seems useful and at another level I worry that it may introduce some of C++'s inflexibility where it's not always wanted.

Show
Russell Owen added a comment - Tim Jenness this is a bit of distraction but...do you anticipate using type annotations everywhere or only in select places? I haven't used it much yet. At one level it seems useful and at another level I worry that it may introduce some of C++'s inflexibility where it's not always wanted.
Hide
Krzysztof Findeisen added a comment -

Jonathan Sick following Sphinx's lead seems like a good idea (though if I understand things correctly, the autolinking only works if we were to start writing function docs in RST instead of docstrings?). No objections from me.

Show
Krzysztof Findeisen added a comment - Jonathan Sick following Sphinx's lead seems like a good idea (though if I understand things correctly, the autolinking only works if we were to start writing function docs in RST instead of docstrings?). No objections from me.
Hide
Tim Jenness added a comment -

Russell Owen I don't think we have plans to require it. Python ignores them anyhow. They are solely for linters but if we are writing out the types anyhow in the docstrings it seems a waste if we could put them in a slightly different place and get some additional feedback from tooling.

Show
Tim Jenness added a comment - Russell Owen I don't think we have plans to require it. Python ignores them anyhow. They are solely for linters but if we are writing out the types anyhow in the docstrings it seems a waste if we could put them in a slightly different place and get some additional feedback from tooling.
Hide
Jonathan Sick added a comment -

I think we've reached consensus on all four proposals, including a decision to move to a PEP 484-like syntax for describing container types. Work will move to DM-16827 to implement this.

Show
Jonathan Sick added a comment - I think we've reached consensus on all four proposals, including a decision to move to a PEP 484-like syntax for describing container types. Work will move to DM-16827 to implement this.

## People

• Assignee:
Jonathan Sick
Reporter:
Jonathan Sick
Watchers:
John Parejko, Jonathan Sick, Kian-Tat Lim, Krzysztof Findeisen, Meredith Rawls, Russell Owen, Tim Jenness