Specification: Commenting of Modules and Classes with Specification References

Purpose

Defines the required structure and content for module and class docstrings, ensuring clear traceability to the relevant specifications and unambiguous documentation of implementation coverage.

Scope and Boundaries

  • In scope: All Python modules and classes in the codebase.

  • Out of scope: Function/method docstrings (unless they implement spec-level requirements).

  • Dependencies: Relies on the existence of up-to-date specifications in /specs/.

Detailed Requirements

1. Module Docstrings

  • Required at the top of every module.

  • Structure:

    1. Short description of the module’s purpose.

    2. Implements section:

      • List all relevant specifications using the format:

        Implements :any:`/specs/<spec_file>` §<section>, covering:

- <summary of covered sections>

      • If multiple specs are relevant, list each with section numbers and a summary.

      • Lists and paragraphs must be surrounded by empty lines.

    3. Optional: List of key classes/functions provided by the module.

  • Example:

    """
Domain models for gitlab_overviewer.

Provides data structures for groups, projects, issues, and readme extraction.

Implements :any:`/specs/spec_model_mapping` §1-5, covering:

* :class:`Group` -- GitLab group model
* :class:`Project` -- GitLab project model
* :class:`Issue` -- GitLab issue model
* :class:`Readme` -- Project readme model
* :class:`ReadmeExtract` -- Extracted readme content
* :class:`OverviewData` -- Aggregated overview data

See also: :mod:`gitlab_overviewer.models.group`, :mod:`gitlab_overviewer.models.project`, :mod:`gitlab_overviewer.models.issue`, :mod:`gitlab_overviewer.models.readme`, :mod:`gitlab_overviewer.models.readme_extract`, :mod:`gitlab_overviewer.models.overview_data`
"""

2. Class Docstrings

  • Required for every class.

  • Structure:

    1. Short description of the class.

    2. Implements section:

      • List all relevant specifications and sections, using the format:

        Implements :any:`/specs/<spec_file>` §<section>, providing:
- <summary of responsibilities>

      • If the class only partially implements a spec, clarify which parts are covered.

      • Lists and paragraphs must be surrounded by empty lines.

    3. Optional: List of key attributes or methods, if not obvious.

  • Example:

    class OverviewData(BaseModel):
    """Container for all data related to a project overview.

    Implements :any:`/specs/spec_table_rendering_ui` §2, providing:

    * Computed column values (repo, type, priority, urgency, etc.)
    * Formatted cell values (dates, star ratings, issue counts)
    * Placeholder handling for missing data
    """

3. Specification Linking

  • Use :any: for Sphinx cross-references, or direct Markdown links if outside Sphinx context.

  • Always include section numbers (§2, §3.1, etc.) for precise traceability.

  • If a module/class implements multiple specs, list each with a summary of what is covered.

4. Open Questions and TODOs

  • If there are open questions or incomplete spec coverage, include a TODO or Open questions section in the docstring.

5. Consistency and Maintenance

  • Update docstrings when implementation coverage changes or when specs are updated.

  • Ensure that docstrings and spec references remain accurate and up-to-date.

Error Handling

  • If a module or class does not fully implement the referenced spec, this must be clearly stated in the docstring.

  • If a referenced spec or section is missing, raise a documentation warning during review.

Testing Requirements

  • Automated or manual checks should ensure that all modules and classes have docstrings following this specification.

  • Docstrings should be checked for valid spec references and section numbers.

Quality Checklist

  • [ ] Every module and class has a docstring.

  • [ ] Docstrings include spec references with section numbers.

  • [ ] Partial implementations are clearly indicated.

  • [ ] Open questions and TODOs are documented.

  • [ ] Docstrings are updated when implementation or specs change.

Common Pitfalls to Avoid

  • Vague references: Always specify section numbers and summarize coverage.

  • Outdated references: Update docstrings when specs change.

  • Missing docstrings: Every module and class must have a docstring.