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

[David Abrahams]

From: "Guido van Rossum" <guido@python.org>
> Alas, I find both the input and the output of the reST-ized version
> worse than the original.  The original takes up much less vertical
> space, which (given the goal of being a relatively terse hint rather
> than formal reference docs) counts for more than bullets, boxes and
> color.  The situation would be different if the goal was to replace
> the reference docs, but since it isn't, I think the informal markup is
> just fine.

I have to agree with Guido, for the same reasons. I wonder if it's the
input markup that's "wrong", or if it just needs a better backend for
generating HTML from the markup.

Incidentally, I'm really excited about reST. I've been looking for a
tolerable markup for C++ comments, and reST looks like it might fit the
bill.

Other musings:

A reST-based Wiki would give people an easy way to see how they like the
format.

Is it just me, or are docstrings less-convenient than comments? Any
thought given to reST-processing a module's comments?

-Dave