[Python-Dev] PEP 287: reStructuredText Standard Docstring Format (original) (raw)

Tom Emerson tree@basistech.com
Wed, 3 Apr 2002 21:15:55 -0500

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"