Adopt a documentation standard?

[mwermelinger]

Should this project adopt the docstring style from Google or Numpy or is it overkill for these library functions?
For a quick overview of both styles, see the documentation of the sphinx napoleon extension.

The styles can be checked with a pylint extension. By default it doesn't check for the presence of the sections. I guess one can use # pylint: disable= to allow for optional sections in some docstrings.

Pydocstyle can auto-detect the style of each docstring. It should be configurable in pyproject.toml with convention = "numpy", for example.

Google style

• Function/method docstrings:
  • have Args:, Returns:/ Yields: and Raises: sections, but they are optional if the typing annotations and one-line summary are sufficient to understand the argument and return values
  • don't document exceptions raised when the arguments fail the pre-conditions
  • can be descriptive ("Returns ...") or imperative ("Return ...")
• Class docstrings:
  • have an Attributes: section for public attributes
  • describe what a class instance represents, e.g. 'A LIFO sequence' for the Stack class

Numpy style

• the one-line summary doesn't repeat the function/method and parameter names
• function/method docstrings:
  • non-optional Parameters and Returns/Yields sections
  • have optional Raises and See also sections (the latter refers to related functions/methods)
  • have optional Notes section to provide more info, e.g. the algorithm used, or to cite papers
  • have optional (but recommended) Examples section for doctests
• class docstrings:
  • include the description of __init__
  • have an optional section Attributes
  • have an optional Methods section to list the most important methods, if the class has many