Docstrings#
This page defines the canonical docstring rules for FRIDOM.
General rules#
Docstrings should be concise, accurate, and written in ASCII only.
Use a short NumPy-style structure when sections are needed. Do not add sections that are unnecessary for the documented object.
Summary line#
The first line should be a single short sentence.
Prefer imperative mood when natural, for example:
Compute ...Create ...Load ...
Module docstrings#
Module docstrings should be one-line summaries.
Use the form:
"""One sentence."""
Do not add any sections to a module docstring.
Functions and methods#
Function and method docstrings should:
start with a short summary line
use short, direct parameter descriptions
use short, direct return descriptions when a Returns section is needed
Methods should not document self or cls as parameters.
The __init__(self, ...) method does not require its own docstring.
Classes#
Class docstrings should document constructor behavior and constructor parameters when needed.
Do not add a separate docstring to __init__(self, ...) when the class
docstring already covers that information.
Do not add a Returns section with None for class docstrings.
Format#
Use this structure for functions and methods when sections are needed:
"""
One sentence.
Parameters
----------
name : type
Short description.
Returns
-------
type
Short description.
"""
Parameter entries should use the form:
name : type
Short description.
Optional parameters should use:
name : type, optional
Short description.
Document *args and **kwargs by name when they are part of the public
API.
Description section#
Include a Description section only if it is explicitly requested.
Otherwise omit the entire section.
When explicitly requested, use:
"""
One sentence.
Description
-----------
Short optional description.
Parameters
----------
name : type
Short description.
Returns
-------
type
Short description.
"""
Type handling#
Use available type annotations when they are present.
If no annotation is present, infer the type conservatively from the code or context.
If the type is an array type such as np.ndarray or ncp.ndarray, write
ndarray.
If the type cannot be determined reliably, use Any.
Do not#
do not invent behavior that is not supported by the code
do not add unnecessary sections such as Notes, Examples, Raises, or See Also unless they are explicitly needed
do not document
selforclsin method parametersdo not add a docstring to
__init__(self, ...)when the class docstring already covers itdo not add multi-line module docstrings
do not add a
Descriptionsection unless it is explicitly requested
Examples#
Module docstring:
"""Utilities for spectral interpolation."""
Function docstring:
"""
Compute the kinetic energy.
Parameters
----------
velocity : ndarray
Velocity field values.
density : float
Reference density.
Returns
-------
ndarray
Kinetic energy values.
"""
Function docstring with an optional parameter:
"""
Load a state from disk.
Parameters
----------
path : str
Path to the input file.
backend : str, optional
Backend name to use.
Returns
-------
State
Loaded model state.
"""
Class docstring:
"""
Create a Cartesian grid.
Parameters
----------
N : tuple[int, int]
Number of grid cells in each direction.
L : tuple[float, float]
Domain lengths in each direction.
periodic_bounds : tuple[bool, bool], optional
Periodicity flags for each direction.
"""
Method docstring:
"""
Advance the model by one time step.
Parameters
----------
dt : float
Time-step size.
Returns
-------
None
Update the model state in place.
"""