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

[Jeremy Hylton]

David,

I just posted a squishy comment on PEP 287.  I realized that I can be
more specific: PEP 287 describes a general-purpose structured text
format "allowing for all kinds of documents."  It doesn't say much of
anything about docstrings specifically: "This PEP is not concerned
with docstring semantics or processing at all."

I think this is backwards.  The PEP proposes to solve a specific
problem -- docstring formats -- without any discussion of the problem
domain or its requirements.  Moreover, I disagree with goal 5.  I
think it is a non-goal to write a module's entire documentation in
docstrings.  (Perhaps it should be a goal that the docstring format is
*not* right enough to write a module's entire documentation <0.6
wink>.)

I think there two missing goals that are essential for a PEP that will
make people happy:  The first goal should be to keep the markup as
simple as possible.  The second goal should be to be targetted
specifically at the needs of people who write docstrings for the
standard library.

I think it would also be productive to see an example or two of how
this new format would be used in the standard library.  Take a module
that already has some decent docstrings and re-write it in the new
format.  Then we can see what benefit results from the effort.  And
take a module without docstrings and write new ones.

   (Some candidates: string, random, and unittest have good
   docstrings.  getopt and hmac aren't bad.  weakref is relatively
   small and doesn't have any docstrings.)

If the primary goal is to keep the markup simple, I think it's
impossible to judge a candidate without knowing what markup is
required for docstrings.  

I am uncomfortable with the PEP's argument that "The problem is that a
construct that seems superfluous to one person may be absolutely
essential to another."  A good design for a docstring format makes
some hard decisions about what actually is essential and what is
bloat.  To paraphrase Aristole, wisdom comes from choosing wisely in
the particular situation.

Jeremy