Should I document all the parameters, exceptions and return values of a function, even if they are already documented in other functions? (Python)

Question

I've noticed that in many functions the same parameters are repeated. Example:

def run_inspection(first_panel, last_panel, results, settings, references, 
               registration_settings):
"""
Runs multithreading for inspection stage.

Args:
    first_panel (int): Number of the first panel to be inspected.
    last_panel (int): Number of the last panel to be inspected.
    results (data_management.StaticVar): Contains the results string.
    settings (dictionary): General settings dictionary.
    references (list): Contains dictionaries of references data.
    registration_settings (dictionary): Contains data about the registration process.

Raises:
    excepts.FatalError("WRONG_UV_INSPECTION_FLAG"): If the parameter 
        to define if UV light will be used has an incorrect value.

Returns:
    total_time (float): Time it took to create results.
"""

and

def run_debug(first_panel, last_panel, results, settings, references):
"""
Runs multithreading for debug stage.

Args:
    first_panel (int): Number of the first panel to be inspected.
    last_panel (int): Number of the last panel to be inspected.
    results (data_management.StaticVar): Contains the results string.
    settings (dictionary): General configuration dictionary.
    references (list): Contains dictionaries of references data.

Raises:
    excepts.FatalError("WRONG_UV_INSPECTION_FLAG"): If the parameter 
        to define if UV light will be used has an incorrect value.

Returns:
    total_time (float): Time it took to create results.
"""

These parameters are constantly repeated in many functions (more than six). Some functions that use these parameters aren't related to each other.

Should I document all the parameters, exceptions and return values of a function, even though they are already documented in many other functions?

If there are parameters that are common throughout the module, you might want to document them in a central place, like the `README.md` file of the github repo. — Barmar, Dec 26 '20 at 19:05
If you don't have a style guide or reference then it is at your personal preference. My personal preference, if I would take the trouble to prepare such extensive documentation, then I would make it consistent and complete. That is, I would document every parameter in every function. For the related functions, as a shortcut, I would document the parameters in one function (e.g. the most used one) and then reference this documentation in the related functions with a note like "same as in function foo()." For the unrelated functions I would duplicate the descriptions not to confuse the reader. — SergiyKolesnikov, Dec 26 '20 at 19:37

Maxim Wandrowski · Answer 1 · 2020-12-26T22:41:26.913

Yes.

How would somebody know to look for that information inside another function? Always put yourself into the shoes of the developer consuming your package for the first time. This is precisely the moment your documentation matters. Remember:

You are writing code for people and not machines. Writing code for machines would be binary without comments.

I like your question because you're touching on a fundamental problem with python docstrings: Maintaining related docstrings is tedious and error prone. A classic example of WET code.

The much more interesting question is therefore how to reuse docstring sections across your projects in an intelligent way. This is discussed in other StackOverflow questions and even a matplotlib issue on GitHub:

There is also the docrep python package dedicated to this issue. Choose your poison ;-)

Should I document all the parameters, exceptions and return values of a function, even if they are already documented in other functions? (Python)

1 Answers1