[kohlerca]

The optional arguments in Elephant functions should be clearly documented in the docstring text.

The style adopted in Elephant asks for identifying the argument as optional with an , optional after the type list, and to include the default value defined in the function header as a last line starting with Default: . In this line, trailing periods are not allowed to avoid errors if copying the value from the documentation page.

Some inconsistencies were identified across the library, and to correct and prevent future errors, a custom Sphinx extension is being added to identify disagreements between the function declaration and the corresponding docstring.

The extension is added to doc/_ext as defaults_validation.py.

The following rules/behavior were defined:

1. Optional marker. The parameter type list must end with , optional, with no space between the type list and the comma. The marker states that the caller may omit the argument, which is exactly what a signature default means. Parameter entries documented without type specifications are not checked.

2. Default line present. The description block must contain a line that starts with Default: followed by a space, matched case-sensitively.

3. Default line last. The Default: line must be the last non-empty line of the description block.

4. No separate paragraph. A blank line must not precede the Default: line, unless it closes an indented block or a list, where
   reStructuredText requires it.

5. Default value correct. The text following Default: must match the default expression from the signature, or start with it followed by parenthetical extra text. The comparison is exact and is made against a canonical rendering of the expression, not against its source text, so 15*pq.ms is documented as Default: 15 * pq.ms and spikes="random" as Default: 'random'. An integer literal is rendered as it is written. A float literal keeps the notation of the signature, canonicalized by these forms:

   • A missing fractional or integer digit is filled with a zero, so 1. is documented as Default: 1.0 and .5 as Default: 0.5.
   • Scientific notation is preserved instead of expanded, and the exponent marker is lowercase, so 1E-5 is documented as Default: 1e-5 and 1e3 as Default: 1e3.
   • The exponent carries no + sign and no leading zero, so 1e+05 is documented as Default: 1e5.
   • The mantissa of an exponent literal carries no trailing . and no trailing .0, so 1.e-3 and 1.0e-3 are both documented as Default: 1e-3, while 1.5e-3 keeps its fractional digit.

   The notation mirrors the signature in both directions: a signature written 0.001 rejects Default: 1e-3, and a signature written 1e-3 rejects Default: 0.001.

6. Extra text in parentheses. Any text after the default value must be enclosed in parentheses immediately after the value, such as Default: -1 (the last axis). The parenthesis must fit on the Default: line; a longer explanation belongs in the Notes section, referenced from the parenthesis as in Default: None (see Notes [1]).

7. No trailing period. The Default: line must not end with a period.

8. None default is annotated. A parameter whose signature default is None and which carries a type hint annotation must have a type hint annotation that admits None. These annotations can be written as Optional[X], X | None or Union[X, None]. The type hint form x: list[int] = None is a type error under PEP 484, which dropped implicit optionality.

The build configuration in doc/conf.py was updated, and all the errors flagged were corrected.

[coveralls]

coverage: 45.696% (-42.9%) from 88.605% — INM-6:feature/docstring_defaults_validation into NeuralEnsemble:master

[CozySocksAlways]

Link to PR number?

[kohlerca]

Added reference to PR #673

[CozySocksAlways]

Add citation for this, maybe on PR 693

[kohlerca]

Added to PR #693. It will have to be merged into master first to carry over the changes and avoid conflicts.