Preferred syntax for the docstrings

[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