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

user_11547816 0
Viewed 197

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?

docstring documentation parameters python
1 Answers

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 ;-)

user_130780710
Related