numpy / numpy/numpydoc

Validating Enum doc-strings?

Open
#458 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
355
Forks
181
Avg merge
1d 9h
Merged PRs (30d)
3

Description

Not sure if it is just me, but I get the following warning when validating an Enum:

WARNING: [numpydoc] Validation warnings while processing docstring for 'b_asic.quantization.Quantization.ROUNDING':
  GL01: Docstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)
  GL02: Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)

The code looks like:

class Quantization(Enum):
    """Quantization types."""

    ROUNDING = 1
    """
    Standard two's complement rounding, i.e, tie rounds towards infinity.
    """

Is there a more correct way to document enums or is this just something that is not completely covered in the validation?

Edit: I should mention that I have tried several different ways to format the doc-string as well.

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

Start with the numpydoc validation warnings for b_asic.quantization.Quantization.ROUNDING and compare the shown Enum member docstring with the validation rules. Check whether Enum member docstrings are supported and whether the warning is expected; done means the supported formatting or required validation behavior is clearly established.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.