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

[Tom Emerson]

Guido van Rossum writes:
> > Why does the community need a new structured text design? What is
> > wrong with existing markup methodologies? The PEP didn't answer these
> > with any cogent examples, IMHO.
> 
> Maybe that's because it's obvious to anyone who has hung out on
> doc-sig long enough.

So in order to understand a PEP one needs to subscribe to all
applicable mailing lists?

> Structured text is really a great idea for certain situations; reST
> is a much better implementation of the idea than any versions I've
> seen before.  E.g. the ST code in Zope stinks (this is not a
> secret).

I have no idea what is better. I ju

> > The only rationale that I saw was existing use: the people that
> > already make use of it find it natural, and everyone else has to learn
> > it.
> 
> Maybe David needs to write up the rationale better.  But I can assure
> you there is one.

Obviously so, else he wouldn't have written the PEP in the first
place. But the rationale in the PEP didn't convince me that it was
worth my time to blindly adopt a new markup scheme that I've never
used to document classes in the Python libraries and application I'm
writing merely to make use of the documentation tools that are
provided.

Instead the greater motivation is to adopt JavaDoc/Doxygen and write
appropriate tools, since most developers already speak enough HTML to
write the reference documentation.

Of course there is a lot of current practice which has the
momentum. Given how carefully rationalized the other PEPs are, there
is no reason to not make 287 equally rationalized.

Devil's-advocately-yours,

tree

-- 
Tom Emerson                                          Basis Technology Corp.
Sr. Computational Linguist                         http://www.basistech.com
  "Beware the lollipop of mediocrity: lick it once and you suck forever"