-
Notifications
You must be signed in to change notification settings - Fork 4
Docstrings
Why validate docstrings?
Historically, there was no validation on how docstrings were written. Some conventions were usually followed, but as the project grew, it was more difficult to ensure that all the API documentation pages are consistent, and don't have mistakes.
For the last two years, we've been implementing all sorts of validations to make sure every class, method, function and attribute is correctly documented.
Where can I find the list of validations? You can find the list of validations in the table below, while you can view the Good & Bad examples of each error in this page.
| Error Code | Error Description | Is Completely Validated? |
|---|---|---|
| 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 | No |
| 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) | No |
| GL03 | Double line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstrings | Yes |
| GL04 | Private classes ({mentioned_private_classes}) should not be mentioned in public docstrings | Yes |
| GL05 | Tabs found at the start of line "{line_with_tabs}", please use whitespace only | Yes |
| GL06 | Found unknown section "{section}". Allowed sections are: "{allowed_sections}" | Yes |
| GL07 | Sections are in the wrong order. Correct order is: {correct_sections} | Yes |
| GL08 | The object does not have a docstring | No |
| GL09 | Deprecation warning should precede extended summary | Yes |
| GL10 | reST directives {directives} must be followed by two colons | Yes |
| SS01 | "No summary found (a short summary in a single line should be present at the beginning of the docstring) | Yes |
| SS02 | Summary does not start with a capital letter | Yes |
| SS03 | Summary does not end with a period | Yes |
| SS04 | Summary contains heading whitespaces | Yes |
| SS05 | Summary must start with infinitive verb, not third person '(e.g. use "Generate" instead of "Generates")' | Yes |
| SS06 | Summary should fit in a single line | No |
| ES01 | No extended summary found | No |
| PR01 | Parameters {missing_params} not documented | No |
| PR02 | Unknown parameters {unknown_params} | No |
| PR03 | Wrong parameters order. Actual: {actual_params} Documented: {documented_params} | Yes |
| PR04 | Parameter "{param_name}" has no type | Yes |
| PR05 | Parameter "{param_name}" type should not finish with "." | Yes |
| PR06 | Parameter "{param_name}" type should use "{right_type}" instead of "{wrong_type}" | No |
| PR07 | Parameter "{param_name}" has no description | No |
| PR08 | Parameter "{param_name}" description should start with a "capital letter" | No |
| PR09 | Parameter "{param_name}" description should finish with "."' | No |
| PR10 | Parameter "{param_name}" requires a space before the colon separating the parameter name and type | Yes |
| RT01 | No Returns section found | Yes |
| RT02 | The first line of the Returns section should contain only the type, unless multiple values are being returned | No |
| RT03 | Return value has no description | No |
| RT04 | Return value description should start with a capital letter | Yes |
| RT05 | Return value description should finish with "." | Yes |
| YD01 | No Yields section found | No |
| SA01 | See Also section not found | No |
| SA02 | Missing period at end of description for See Also '"{reference_name}" reference | Yes |
| SA03 | Description should be capitalized for See Also '"{reference_name}" reference | Yes |
| SA04 | Missing description for See Also "{reference_name}" reference | No |
| SA05 | {reference_name} in See Also section does not need pandas prefix, use {right_reference} instead. |
Yes |
| EX01 | No examples section found | No |
| EX02 | Examples do not pass tests:\n{doctest_log} | No |
| EX03 | flake8 error: {error_code} {error_message}{times_happening} | No |
| EX04 | Do not import {imported_library}, as it is imported automatically for the examples (numpy as np, pandas as pd) | Yes |
What are the list of pending errors?
You can view the list of pending errors in the dashboard.
Some of them are formatting errors. Some of them makes more sense to work when fixing the content of an object (like adding the description, or objects that simply don't have any documentation).