---
title: Docstring and Spec-Linking Guidelines
---

# 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**:
  ```python
  """
  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**:
  ```python
  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.

---

## Related Rules
- [Specification Writing Guidelines](mdc:spec-guidelines)
- [Spec Compliance Investigation Guide](mdc:spec-compliance-investigation)

---

**This specification ensures that all code is traceable to the requirements it implements, and that documentation remains clear, precise, and maintainable.**