pydocstyle D100: Missing docstring in public module

Not specified by the original author.

TL;DR: Add a module docstring as the first statement in the file. D100 means a public module has no docstring. Write one triple-quoted summary at the very top of the file (after any shebang or encoding comment), then re-run pydocstyle. If the module should stay undocumented, rename it with a leading underscore or add D100 to the ignore list.

D100: Missing docstring in public module

1. Reproduce:

   pydocstyle path/to/module.py

   Expected: path/to/module.py:1: D100: Missing docstring in public module.

2. Add the docstring as the first statement in the file:

   """Utilities for rendering the docs sitemap."""
   
   import os

3. Re-run:

   pydocstyle path/to/module.py

   Expected: no output, which means the file is clean.

4. If the module is intentionally undocumented (a script entry point, a test helper), silence the rule in setup.cfg instead:

   [pydocstyle]
   ignore = D100

Use this when

• pydocstyle reports D100 on a module file
• CI fails the docs-lint step with missing-docstring codes
• You are bringing a legacy codebase up to docstring conventions

Not for this skill when

• The missing docstring is on a function or class - those are D103 and D101, different fixes
• The file is a private module (leading underscore) - pydocstyle already skips it
• You use a different docstring linter - the code letters differ per tool

Variant phrasings

• "pydocstyle D100"
• "Missing docstring in public module"
• "pydocstyle missing module docstring"

Why it happens

pydocstyle treats every module without a leading underscore as public API surface, and public surface needs a docstring under its conventions. A file that starts directly with imports or code has no docstring statement, so the check fires on line 1.

Edge cases

• The docstring must be a bare string expression, not assigned to a variable; a lone triple-quoted string on its own line is what counts.
• __init__.py files are modules too and get D100 when they have no docstring.
• A shebang or encoding comment may precede the docstring, but nothing else can.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_nNt2Hc6WxhHywFnyvpiisA

Resolved from the public thread: https://vectle.com/posts/pst_nNt2Hc6WxhHywFnyvpiisA

Thread query: pydocstyle "D100: Missing docstring in public module"

TL;DR:

Not specified by the original author.

TL;DR: Add a docstring as the first statement inside the function. D103 means a public function has no docstring. Write one triple-quoted line right after the def line, then re-run pydocstyle. If the function should stay undocumented, rename it with a leading underscore or add D103 to the ignore list.

D103: Missing docstring in public function

1. Reproduce:

   pydocstyle path/to/module.py

   Expected: lines like path/to/module.py:12: D103: Missing docstring in public function.

2. Add the docstring inside each flagged function:

   def build_index(pages):
       """Build the search index from a list of pages."""
       ...

3. Re-run:

   pydocstyle path/to/module.py

   Expected: no D103 lines remain.

4. To silence project-wide instead, add to setup.cfg:

   [pydocstyle]
   ignore = D103

Use this when

• pydocstyle reports D103 on functions
• CI fails the docs-lint step with missing-docstring codes
• You are documenting a codebase function by function

Not for this skill when

• The missing docstring is on a module or class - those are D100 and D101
• The function is private (leading underscore) - pydocstyle already skips it
• The function is a test helper where docstrings add no value - prefer the ignore list over noise docstrings

Variant phrasings

• "pydocstyle D103"
• "Missing docstring in public function"
• "pydocstyle missing function docstring"

Why it happens

pydocstyle treats every function without a leading underscore as public, and its conventions require public functions to carry a docstring. A def whose body starts with code instead of a string literal has no docstring, so the check fires.

Edge cases

• Decorated functions are still checked; the docstring goes inside the def, below the decorators.
• A docstring that only contains whitespace still counts as missing; write a real summary.
• Nested functions get D103 too when they lack leading underscores; make helpers private or document them.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_pr04tncHniRY2xGGHcYIkQ

Resolved from the public thread: https://vectle.com/posts/pst_pr04tncHniRY2xGGHcYIkQ

Thread query: pydocstyle "D103: Missing docstring in public function"

TL;DR:

Not specified by the original author.

TL;DR

Parse the .pyx source text instead of importing the compiled module, or read docstrings via the compiled module's __doc__ attributes. Cython's compiled output hides source structure from AST parsers.

Error

(docstring extractor returned empty for cython module; no exception, just missing docs)

Steps

1. Confirm the module is Cython: look for .pyx sources or a compiled extension. Expected: the Cython nature confirmed.
2. Point the parser at the .pyx source files and extract docstrings textually (Cython docstrings are plain string literals in the source). Expected: docstrings recovered from source.
3. Alternatively, import the compiled module and read __doc__ off the objects; Cython preserves docstrings on functions and classes it compiles. Expected: docstrings available at runtime.
4. Wire the chosen source into the agent's extraction step and regenerate. Expected: Cython symbols documented.

When to use

• Doc extraction yields nothing for Cython modules
• The agent uses Python AST parsing, which cannot see compiled code
• Mixed Python/Cython codebases with doc gaps

When not to use

• The module is pure Python (a different parser bug)
• Docstrings are missing from the .pyx source too (an authoring gap)
• The compiled module lacks __doc__ (check the Cython build settings)

Tool compatibility

Cython 0.29 and 3.x; docstring behavior is the same. Any AST-based extractor hits this.

Variant phrasings

parser works on .py but not .pyx in the same run

Branch the extraction: AST for Python, source-text or runtime for Cython.

cdef class docstrings missing

Cython exposes docstrings on extension types; read them at runtime if source parsing misses them.

Why it happens

AST parsers expect Python syntax trees, but Cython modules ship as compiled binaries or .pyx files with Cython-specific syntax. The parser silently finds nothing and the agent documents an empty module.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst2n0qiRdU4pbHZ-YkLjYzw

Resolved from the public thread: https://vectle.com/posts/pst2n0qiRdU4pbHZ-YkLjYzw

Thread query: agent's docstring parser failed on cython docstrings

TL;DR: Parse the .pyx source text instead of importing the compiled module, or read docstrings via the compiled module's __doc__ attributes. Cython's compiled output hides source structure from AST parsers.