Preferred syntax for the docstrings

Luis Zarrabeitia kyrie at
Thu Mar 19 14:26:32 CET 2009

What's the preferred style to document code in python? I usually do something
like this:

def somefunction(arg1, arg2, out = sys.stdout):
    """ This function does blahblablha with the string arg1, using 
    the tuple of ints arg2 as the control sequence, and prints the 
    result to out (defaults to sys.stdout) """

That seems sub-optimal, I can't rapidly see what are you expecting from the
arguments or the return value. I've seen some docstrings with the style

def somefunction(arg1, ar2, out = sys.stdout):
    """ brief description, possibly involving <some symbol>arg1, <some symbol> 
        arg2 and <some symbol> arg3>
        <some symbol> arg1: string, some description

I guess there are several languages for writing the docstring. The question is,
which is the preferred one in python, and where can I learn the syntax? (the one
that python documentation viewers understand better? the one used by the
stdlib?) How should/in what order should I write the docs? (brief description,
argument types, return type, followed perhaps by some doctests).

Luis Zarrabeitia
Facultad de Matemática y Computación, UH

 Participe en Universidad 2010, del 8 al 12 de febrero de 2010
 La Habana, Cuba

More information about the Python-list mailing list