search

bgr / mingus

Automatically exported from code.google.com/p/mingus
GNU General Public License v3.0
1 stars 1 forks source link

docstrings should be PEP 257 compliant #109

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
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 commented 9 years ago 
to chose → to choose

sorry...

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

GoogleCodeExporter commented 9 years ago 
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 commented 9 years ago 
I'm working on generate_wiki_docs.py.

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

GoogleCodeExporter commented 9 years ago 
This issue was closed by revision 5fb5ba43bac4.

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