Inconsistent indication of types in docstrings

[alvorithm]

Problem

We have a variety of styles, including

• Pyro-style (warranted where looking forward to near-term integration in Pyro)
• name: type, explanation (for example - inputs: torch.tensor(), parameters theta)
• name (type): explanation (for example - num_samples (int): desired number of samples). This is what PyTorch uses
• variants of the above using braces { } or square brackets [ ] for the type

Suggested solution

Adopt the PyTorch convention across the board or elimitate types completely given that we're going to specify them in the signature already. This is what thinc does - loss.py example, and would be @Meteore 's favorite.

Action

1. @jan-matthis @janfb @michaeldeistler: argue & vote in the comments.
2. once decided, adjust if necessary the plugin that is generating the stubs for you.

FYI I get PyTorch-style docstring templates from VSCode's plugin autoDocstring by Nils Werner (0.4.0).

[michaeldeistler]

I'm fine with pyTorch style

[jan-matthis]

Pyro style docstrings in the slice sampler are on purpose, makes it's easier to potentially contribute the slice sampling kernel (so this should be a warranted inconsistency).

For the rest of the code base, I also think it's easiest to just use type annotations in the signature and avoid duplication in the docstring, so just use name: explanation.

[alvorithm]

OK, then if Jan agrees we keep this issue open and reference it from a sanitize-docstrings PR (to be created).

[jan-matthis]

Here is a template for VSCode's autoDocstring without types:

{{! Google Docstring Template without types }}
{{summaryPlaceholder}}

{{extendedSummaryPlaceholder}}

{{#parametersExist}}
Args:
{{#args}}
    {{var}}: {{descriptionPlaceholder}}
{{/args}}
{{#kwargs}}
    {{var}}: {{descriptionPlaceholder}}
{{/kwargs}}
{{/parametersExist}}

{{#returnsExist}}
Returns:
{{#returns}}
    {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/returns}}
{{/returnsExist}}

{{#yieldsExist}}
Yields:
{{#yields}}
    {{typePlaceholder}}: {{descriptionPlaceholder}}
{{/yields}}
{{/yieldsExist}}

[alvorithm]

Thank you so much. This has to go in a file AFAICT, do you know what the canonical places/names/extensions would if project local or if global? Which one did you end up choosing?

[jan-matthis]

I also wondered where to put the file, ended up placing it in a autodocstring subfolder relative to my global settings.json

[alvorithm]

I wonder whether with 3 of 4 (currently active) devs using vscode and a mandated format for the docstring it'd be too much of a stretch to version in git .vscode/settings.json and the template. Non-vscode users would not be affected, but could also get documentation (e.g. line length) for their own IDEs by looking at it. What do you think?

[alvorithm]

I put it in ~/.config/Code - Insiders/User/autodocstring.template

[janfb]

Thanks! and where and how do you refer to autodocstring.template in vscode?

[jan-matthis]

Thanks! and where and how do you refer to autodocstring.template in vscode?

I'll answer in #128