PEP 287: reStructuredText Standard Docstring Format

[Delaney, Timothy]

> From: Paul Rubin [mailto:phr-n2002a at nightsong.com]
> 
> David Goodger <goodger at users.sourceforge.net> writes:
> > Here's a serious proposal, safe to post now that April 
> Fool's is over.
> > Please read & comment.
> 
> Man, I thought it was an April fools joke when I saw it last night.
> All those `different` :kinds: 'of' "quoting" are much more confusing
> than explicit markup.  So I think it's better to use explicit markup.
> The ultimate explicit system is tangle/weave but that's a bit extreme.
> Javadoc has been very successful in practice and you could do a lot
> worse than just copying it lock stock and barrel.

I use javadoc. I don't like it. What I like least is the explicit markup -
it makes the source code documentation very difficult to read. In javadoc
you have lots of ugly constructions, mixed in with *different*,
inconsistent, ugly constructions if you want anything unusual (for example,
a list). The documentation for my unit tests looks like:

/**
 * Test:
 * <ul>
 *    <li>Class.method1();</li>
 *    <li>Class.method2();</li>
 *    <li>Class.method3().</li>
 * </ul>
 * Fails if:
 * <ul>
 *    <li><code>Class.method1</code> fails.</li>
 *    <li><code>Class.method2</code> fails.</li>
 *    <li><code>Class.method3</code> fails.</li>
 * </ul>
 **/

This is not very easy to read, although it produces nice HTML docs (the
<ul><li></li></ul> is ignored in the summary, but displayed in the
description, the semicolons split up the methods in the summary, the
fullstop terminates the summary).

Compare that to:

"""
Test:

- Class.method1()
- Class.method2()
- Class.method3()

Fails if:

- `Class.method1` fails.
- `Class.method2` fails.
- `Class.method3` fails.
"""

I think I got the above right - I've never read anything about
reStructuredText before. I have implemented a form of structured text for a
specific domain (in VBScript no less ... that was painful).

I read through all the reStructuredText docs, comparing the text versions to
the html versions. I found the text versions to be *very* easy to read,
whilst making it obvious in most cases when something was "special".

I particularly like the system of doing hyperlinks, and much prefer the more
verbose

.. _hyperlink: url

form than the short form.

> The thing I like least about the PEP is that it's written like
> marketing material--it sets out to push a particular solution and
> looks for things to bash about the alternatives rather than treating
> them evenhandedly and being willing to accept the idea that
> reStructuredText may not be the answer.

It does feel somewhat like marketing material in some documents, however the
"alternatives" document dispells that notion. There has obviously been a lot
of thought and discussion put into the system, and the author is shameless
about admitting that a lot of ideas have been stolen.

> widely-deployed, practical systems; a lot of people use them and like
> them and there are REASONS for that.  The PEP should acknowledge their
> success and see if there's something to be learned from it, rather
> than dismissing them so airily.

I think the PEP (and supporting documentation) did a good job of
acknowledging these systems, but quickly concluded that the systems were not
appropriate for the purpose.

Definitely +1 from me ... I would really like a standard, clean docstring
format. Might make it easier to get my next project done in Python (maybe
Jython).

Tim Delaney