docstrings should be PEP 257 compliant

[GoogleCodeExporter]

http://www.python.org/dev/peps/pep-0257/

Basically we have to chose between

def foo():
    """Return bar and baz."""

and

def foo():
    """
    Return bar and baz.
    Raise FooError randomly blah blah,
    blah blah.
    """

(with correct indentation, max. 80 chars for line and no "\").

I also think examples should be removed from docstrings, and auto-generated by 
invoking mingus itself. This[1] could be useful.

Otherwise help() can't work properly.

Regards,
Carlo

[1] http://docs.python.org/library/inspect.html#inspect.cleandoc

Original issue reported on code.google.com by carlo.stemberger@gmail.com on 13 May 2011 at 11:31

[GoogleCodeExporter]

to chose → to choose

sorry...

Original comment by carlo.stemberger@gmail.com on 13 May 2011 at 11:35

[GoogleCodeExporter]

The reason the docstrings look so strange is that they are used to generate the 
reference documentation. I'm all for putting it in a more sane, standard 
format, but we should keep in mind that the reference doc generator should be 
updated accordingly.

Original comment by Rhijnauwen@gmail.com on 18 May 2011 at 7:58

[GoogleCodeExporter]

I'm working on generate_wiki_docs.py.

Original comment by carlo.stemberger@gmail.com on 23 May 2011 at 4:25

• Changed state: Started

[GoogleCodeExporter]

This issue was closed by revision 5fb5ba43bac4.

Original comment by carlo.stemberger@gmail.com on 27 May 2011 at 2:33

• Changed state: Fixed