| name | write-docstrings |
| description | Write or review docstrings for code in this repo. Use when writing new docstrings, reviewing existing docstrings, or editing docstrings. |
| argument-hint | [source code] |
Writing Docstrings
Required for: all public modules, classes, functions, and methods
Format: Google-style
- Do not place type information in docstrings - use type annotations only
- Do not use leading articles in parameter, return, and error descriptions "a", "an", or "the"
- Only use single backticks (e.g.
Spam, not Spam)
Example
def process_spam(input_data: list[tuple[str, int]], threshold: int = 2) -> dict[str, int]:
"""Process spam counts, dropping those below threshold
Args:
input_data: spam counts to process
threshold: minimum count threshold for inclusion
Returns:
Mapping of categories to counts
Raises:
ValueError: threshold is negative
Examples:
>>> process_spam([("jalapeno", 5), ("regular", 3), ("jalapeno", 9), ("low sodium", 1)], 2)
{"jalapeno": 14, "regular": 3}
"""
Incorrect example (do not do this!)
def process_spam(input_data: list[tuple[str, int]], threshold: int = 2) -> dict[str, int]:
"""Process spam counts, dropping those below threshold
Args:
input_data (list[str]): A list of spam counts to process. # ❌ Has type and article
threshold (int): A minimum count threshold for inclusion. # ❌ Has type and article
Returns:
dict[str, int]: A dictionary mapping categories. # ❌ Has type and article
"""
Module and class docstrings
- Module docstrings: single sentence describing the module's purpose; placed at the top of the file before any imports.
- Class docstrings: describe the class's purpose and any important attributes or invariants; placed immediately after the
class line.
Miscellaneous
- Prefer Unicode superscripts for single digit superscripts, e.g. Ų
- Never add ignores to the
pyproject.toml formatting, linting, or type checking without explicitly asking
