[Python-Dev] PEP 287: reStructuredText Standard Docstring Format

David Goodger goodger@users.sourceforge.net
Fri, 05 Apr 2002 22:25:24 -0500

Thanks Jeremy, for raising good points.

Jeremy Hylton wrote in his first message:
> I have always been puzzled by why Python has taken so long to come
> up with some simple conventions for structuring docstrings.

I think there are many factors.  People have different requirements,
and often insist that their minimal set is the best set (thus
reStructuredText is more flexible).  We've seen what else is out
there, and we aren't satisfied.  Python has shown us how readable
code can be, and we strive for readable inline docs as well.  Nobody
has been as committed, driven, and nuts as me before.

> The one time I looked at JavaDoc, it struck me as quite simple

Simple, yes, but ugly as sin.  I wouldn't want JavaDoc in *my*
modules.  Many others concur.

> It also appeared that JavaDoc had a limited feature set, which also
> seemed like a strength: Let's not write fancy, formatted reports in
> docstrings.

This is a common argument, but I think a flawed one.  It assumes that
rich syntax inevitably begets over-complex docs, and at the same time
assumes that no docs ever need to use sophisticated features.

Fine, don't write fancy docstrings.  But what if you need a single little
table?  Or a definition list (like in string.py; see my message to Guido)?
Eventually you'll need something more sophisticated, but the markup is
limited.  You're stuck, you get frustrated, throw the tool out and revert
to plaintext with ad-hoc conventions.

The Python equivalent would be to limit the feature set by eliminating,
say, floats.  Ints ought to be enough for anyone!  Those floats just
cause problems...

> It looks like I can mostly read it, but it seems hard to learn how
> to write.

I think that's because I only gave the spec, without the primer.  Now
that we have a primer, what do you think?

> It seems burdensome to require module authors to learn Python and
> reStructuredText just to contribute to the std library.

I'm not advocating that, never have.  I'll make it clear in the PEP.

Jeremy wrote in his second message:
> If the primary goal is to keep the markup simple...
> A good design for a docstring format makes some hard decisions about
> what actually is essential and what is bloat.

The primary goal isn't just "simple", it's "readable, simple, rich,
easy, and extensible plaintext" (among other things; see
http://structuredtext.sf.net/spec/introduction.html#goals).  These
goals obviously conflict, and the design of the markup has been an
exercise in compromise.  A successful one, I think.  I tried to make
simple and common constructs simple.  Rarer constructs are more
verbose, but since they're rare, it's not such a big deal.

Jeremy wrote in his third message:
> I wouldn't object to seeing this PEP approved as an informational
> PEP that described reST as an optional format for docstrings.

That's all I ever intended; sorry if it seemed otherwise.

> (I'm assuming that there is consensus in the doc-sig that reST is
> the right solution.)

More than ever before, I think.  100% consensus is rarely attained in
any forum (this one included).

David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net