A trivial question that I don't know - document a function/method

[Thomas Passin]

On 10/22/2022 4:58 PM, Paulo da Silva wrote:
> Hi all!
> 
> What is the correct way, if any, of documenting a function/method?
> 
> 1.
> def foo(a,b):
>      """ A description.
>      a: Whatever 1
>      b: Whatever 2
>      """
[snip]
> 5.
>      Any other ...
> 
> Any comments/suggestions are welcome.
> Thanks.
> Paulo


This is not a trivial question - not because it is hard but because it 
is important, and more so when someone else needs to work with your 
code.  It's surprising how easy it is to forget these details about even 
your own code.  Here are some examples of how I like to document 
functions and methods, mostly based on PEP-257, Docstring Conventions 
(https://peps.python.org/pep-0257/) and Guido's style guide before it.

def make_title_from_headline(self, p, h):
     """From node title, return title with over- and underline- strings.

        The leading symbol is chosen based on the indent level of
        the node.

        Note that might different from p.h because of, e.g.,
        directive removal.

        ARGUMENTS
        p -- the node position whose indent level is to be used.
        h -- the headline string to be processed.

        RETURNS
        a string
     """

Key points - include all the arguments and the return.  Capitals help 
lead the eye to the ARGUMENT and RETURNS blocks.  If you use keyword 
arguments, add a KEYWORD ARGUMENTS section.

def plot(self, stackposition=MAIN, clearFirst=True):
     """Plot a 2-D graph.

     ARGUMENTS
     self -- an instance of a PlotManager
     stackposition -- an integer denoting which data set to plot.
     clearFirst -- True if the previous plot should be cleared,
                   else False.

     RETURNS
     nothing
     """

Key point -- if the function/method returns nothing, say so.

class Dataset:
     '''Class to represent a 2D curve.

     ATTRIBUTES
     xdata, ydata -- sequences holding the x or y data sets.
                     Must be the same length.  May be lists or numpy
                     ndarrays.
     auxDataset -- dictionary of auxiliary data sets (e.g., for holding
                   statistical information)
     errorBands -- List of Datasets to hold errors
     orig_filename -- file path, if any,  used to load data (before
                      any transformations have been applied).
     xaxislabel -- label text for the X axis label
     yaxislabel -- label text for the Y axis label
     figurelabel -- label text for the graph of this data
     ymin -- minimum value for Y axis
     ymax -- maximum value for Y axis
     parms -- dictionary of parameters,  Meant to store the
              current values so they can be written to a file.
     '''

If you have the space, these annotations could instead be placed in-line 
in the class's __init__() method.  But it's not often there is enough 
space, and when they are in the docstring they will be extracted and 
displayed by docstring tools, which is a good thing.

Sometimes it can happen that a function/method is is simple and clear 
that its name, and the names of the arguments, make it obvious what 
their meaning is.  But that happens less often than you might think.


- Be concise, but choose clarity over brevity;
- Try to devise good, descriptive names as far as possible;
- A long list of arguments probably should be ordered alphabetically, 
but could also be grouped, with each group ordered.  Otherwise, it is 
useful to list the parameters in the order they appear in the 
function/method signature.
- Be consistent in your docstrings, but remember there will be times 
that it makes more sense to relax the consistency.