Should I document parameters for similar function signatures?

Question

I have some helper functions that, except for the first argument, take the same arguments as the core function. The parameters are thoroughly documented in the core function. Should I copy-paste this documentation to the helper function too, or rather just point to the core documentation?

It that matters, I primarily intend my API reference to be read as HTML generated by Sphinx, and I use the numpydoc style. I didn't find an answer in the numpydoc manual.

EDIT

Here is an MWE:

def core(param0, param1=3, param2=8):
    """Core function with thorough documentation.

    Parameters
    ----------
    param0 : ndarray
        Description.
    param1 : int
        Long description.
    param2 : int
        Long description.

    Returns
    -------
    param_out : ndarray
        Long description

    """
    pass

def helper(param3, param1=3, param2=8):
    """Helper function.

    """
    pass

As you can see, only the first parameter differs in the two functions.

score 3 · Accepted Answer · edited Jun 20 '20 at 09:12

The best, and easiest, way to do this is using Python Sphinx docstring sections from the sphinx.ext.napoleon extension.

Only arguments unique to the helper function need to be explicitly documented, you can remit with a cross-reference to the function/method defining the shared parameters. The Google style guide for Python advises the same reasoning for overloading inherited methods from a base class :

A method that overrides a method from a base class may have a simple docstring sending the reader to its overridden method’s docstring, such as """See base class.""". The rationale is that there is no need to repeat in many places documentation that is already present in the base method’s docstring. However, if the overriding method’s behavior is substantially different from the overridden method, or details need to be provided (e.g., documenting additional side effects), a docstring with at least those differences is required on the overriding method.

Args:

List each parameter by name. A description should follow the name, and be separated by a colon and a space.

The following example:

def core(param0, param1=3, param2=8):
    """Core function with thorough documentation.

    Parameters
    ----------
    param0 : ndarray
        Description.
    param1 : int
        Long description.
    param2 : int
        Long description.

    Returns
    -------
    param_out : ndarray
        Long description

    """
    pass

def helper(param3, param1=3, param2=8):
    """Remaining

    Parameters
    ----------
    param3 : int
        Description.
    Other Parameters
        A short string remitting reader to :py:func:`core` function.
    See Also
        A short string remitting reader to :py:func:`core` function.
    Note
        A short string remitting reader to :py:func:`core` function.
    """
    pass

Would give this result:

According to [numpydoc](https://numpydoc.readthedocs.io/en/latest/format.html) (see item 8), the other parameters should have a distinct section. What do you think about [this solution](https://imgur.com/a/U0pnNP8)? — Zoltán Csáti, Jun 09 '20 at 09:17
Both our solutions used "distinct docstring sections". You used "rtd theme" while I used "alabaster theme", only the HTML is rendered differently (it seems "the sections aren't distinct" in my case, but in fact they are). I think your solution is the same, the difference being I didn't explicitly write the parameters in the "Other Parameters" section, because if you have long signatures (say 20 parameters, with 5 helper functions) it's more concise not to repeat the parameters every time (which in essence is what you're trying to avoid...) — bad_coder, Jun 09 '20 at 10:35
@ZoltánCsáti note I also suggested 3 possible sections that can be used, together if necessary. The style guides omit what to do exactly, most folks don't use the "summary" sections to have 1 less word repeating in their documentation... — bad_coder, Jun 09 '20 at 10:46

Should I document parameters for similar function signatures?

EDIT

1 Answers1

Linked