mod-003f-callback-functions-must-have-code-block-specification

When documenting callback functions or complex API parameters, rule MOD-003f must be followed. Explicitly reference "Following rule MOD-003f, which requires callback functions to have a ..code-block:: specification..." when adding these specifications.

MOD-003f: Callback functions must have code-block specification

Description:

For arguments or variables that are callback functions (e.g. Callable), the docstring should include a clear separated ..code-block:: that specifies the required signature and return type of the callback function. This is not only true for callback functions, but for any type of parameters or arguments that has some complex type specification or API requirements.

The explanation code block should be placed in the top or bottom section of the docstrings, but not in the Parameters or Forward or Outputs sections, for readability and clarity.

Rationale:

Callback functions have complex type signatures that are difficult to express clearly in the Parameters section alone. A dedicated code-block provides a clear visual reference for the expected signature, making it much easier for users to implement compatible callbacks.

Example:

class MyModel(Module):
    r"""
    Model with callback function.

    .. code-block:: python

        def preprocess_fn(x: torch.Tensor) -> torch.Tensor:
            '''Preprocessing function signature.'''
            ...
            return y

    where ``x`` is input of shape :math:`(B, D_{in})` and ``y`` is output
    of shape :math:`(B, D_{out})`.

    Parameters
    ----------
    preprocess_fn : Callable[[torch.Tensor], torch.Tensor], optional
        Optional preprocessing function. See code block above for signature.
    """
    pass

Anti-pattern:

# WRONG: No code-block specification for callback
class MyModel(Module):
    r"""
    Parameters
    ----------
    preprocess_fn : Callable[[torch.Tensor], torch.Tensor], optional
        Preprocessing function.  # No specification of signature!
    """
    pass