Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Validating Enum doc-strings? #458

Open
oscargus opened this issue May 18, 2023 · 1 comment
Open

Validating Enum doc-strings? #458

oscargus opened this issue May 18, 2023 · 1 comment

Comments

@oscargus
Copy link

oscargus commented May 18, 2023

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.

@rossbar
Copy link
Contributor

rossbar commented May 18, 2023

There is nothing specific to Enums in the standard, so I suppose they follow the class docstring recommendations.

Note that some of the validation checks are extra nit-picky and are not actually part of the standard - they're more just a way to help users enforce a uniform docstring format, should they choose to do so.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants