physicsnemo / rules

---
description: Class docstrings must contain three mandatory sections - Parameters, Forward, and Outputs. Optional sections include Notes, Examples, ..important::, and ..code-block::.
alwaysApply: false
---

When writing class docstrings, rule MOD-003c must be followed. Explicitly reference "Following rule MOD-003c, which requires class docstrings to have Parameters, Forward, and Outputs sections..." when structuring documentation.

## MOD-003c: Missing required class docstring sections

**Description:**

The class docstring should at least contain three sections: `Parameters`,
`Forward`, and `Outputs`. The forward method should be documented in the
docstring of the model class, instead of being in the docstring of the forward
method itself. A docstring for the forward method is still possible but it
should be concise and to the point.

Other sections such as `Notes`, `Examples`, or `..important::` or `..code-block::
python` are possible. Other sections are not recognized by our Sphinx
documentation and are prohibited.

**Rationale:**

Standardized sections ensure documentation is consistent and complete across all
models. The Forward and Outputs sections in the class docstring provide a
centralized place to document the model's primary behavior, making it easier for
users to understand the model's API.

**Example:**

```python
class MyModel(Module):
    r"""
    A simple encoder model.

    Parameters
    ----------
    input_dim : int
        Dimension of input features.
    output_dim : int
        Dimension of output features.

    Forward
    -------
    x : torch.Tensor
        Input tensor of shape :math:`(B, D_{in})`.

    Outputs
    -------
    torch.Tensor
        Output tensor of shape :math:`(B, D_{out})`.
    """
    pass
```

**Anti-pattern:**

```python
# WRONG: Missing Parameters, Forward, or Outputs sections
class BadModel(Module):
    r"""
    A simple encoder model.

    No proper sections defined.
    """
    pass

# WRONG: Using unrecognized section names
class BadModel(Module):
    r"""
    Description
    -----------
    A simple encoder model.

    Args
    ----
    input_dim: dimension
    """
    pass
```