quickshotdevs team mailing list archive
-
quickshotdevs team
-
Mailing list archive
-
Message #00134
Re: Standard docstring format
On Sun, Apr 18, 2010 at 11:34 PM, Neil Tallim <red.hamsterx@xxxxxxxxx> wrote:
> There are two major Python documentation formats, and we kinda need to
> pick one so that our code can have a consistent look and
> auto-generated documentation.
>
> Epytext (http://epydoc.sourceforge.net/manual-epytext.html)
> Personally, this is my preference. It's flexible, produces
> great-looking documentation, and allows everything to be described,
> without ambiguity.
>
> reStructuredText
> (http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html)
> This is more commonly found in the Python community, since it strikes
> the sweet spot between depth of information, quality of presentation,
> and effort.
>
>
> My vote's for Epytext, but I work with reStructuredText enough to not
> mind switching.
>
> Also, regarding the docstrings themselves, I like the three-line
> format most, for consistency, rather than brevity.
>
> def xyz():
> """
> This is how I'd write a one-line docstring.
> """
> pass
>
>
> Post your comments and we'll go with whatever seems most popular.
>
> -Neil
>
I don't have any preference for either, so whatever is most
popular/well known is fine by me.
--
Simon Vermeersch
Follow ups
References