L
Luis Zarrabeitia
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
http://profesores.matcom.uh.cu/~kyrie
Participe en Universidad 2010, del 8 al 12 de febrero de 2010
La Habana, Cuba
http://www.universidad2010.cu
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
http://profesores.matcom.uh.cu/~kyrie
Participe en Universidad 2010, del 8 al 12 de febrero de 2010
La Habana, Cuba
http://www.universidad2010.cu