physicsnemo / rules

---
description: Docstrings should include an Examples section with executable code demonstrating usage, as these are automatically tested by CI for correctness.
alwaysApply: false
---

When writing model docstrings, rule MOD-003j should be followed. Explicitly reference "Following rule MOD-003j, which encourages an Examples section that CI will automatically test..." when adding examples.

## MOD-003j: Docstrings should include Examples section

**Description:**

Docstrings are strongly encouraged to have an `Examples` section that
demonstrates basic construction and usage of the model. These example sections
serve as both documentation and tests, as our CI system automatically tests
these code sections for correctness when present.

Examples should be executable Python code showing typical use cases, including
model instantiation, input preparation, and forward pass execution. The examples
should use realistic tensor shapes and demonstrate key features of the model.

**Rationale:**

Example sections provide immediate value to users by showing concrete usage
patterns. By automatically testing these examples in CI, we ensure that
documentation stays synchronized with code and that examples remain correct as
the codebase evolves. This catches API changes that would otherwise break user
code without warning.

**Example:**

```python
class MyEncoder(Module):
    r"""
    A simple encoder network.

    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})`.

    Examples
    --------
    >>> import torch
    >>> from physicsnemo.models import MyEncoder
    >>>
    >>> # Create model
    >>> model = MyEncoder(input_dim=784, output_dim=128)
    >>>
    >>> # Process a batch
    >>> x = torch.randn(32, 784)
    >>> output = model(x)
    >>> output.shape
    torch.Size([32, 128])
    """
    pass
```

**Anti-pattern:**

```python
# Not wrong, but strongly discouraged - no Examples section
class MyEncoder(Module):
    r"""
    A simple encoder network.

    Parameters
    ----------
    input_dim : int
        Dimension of input features.
    """
    pass
```