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: .. code-block:: python """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: .. code-block:: python """ One sentence. Parameters ---------- name : type Short description. Returns ------- type Short description. """ Parameter entries should use the form: .. code-block:: python name : type Short description. Optional parameters should use: .. code-block:: python 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: .. code-block:: python """ 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 ``self`` or ``cls`` in method parameters - do not add a docstring to ``__init__(self, ...)`` when the class docstring already covers it - do not add multi-line module docstrings - do not add a ``Description`` section unless it is explicitly requested Examples -------- Module docstring: .. code-block:: python """Utilities for spectral interpolation.""" Function docstring: .. code-block:: python """ 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: .. code-block:: python """ 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: .. code-block:: python """ 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: .. code-block:: python """ Advance the model by one time step. Parameters ---------- dt : float Time-step size. Returns ------- None Update the model state in place. """