[Doc-SIG] New PEP: reStructuredText Standard Docstring Format

[David Goodger]

The updated PEP can be found at
http://docutils.sourceforge.net/spec/pep-xxxx.txt,
until it's assigned a number.

Tony J Ibbs (Tibs) wrote:
> 1. It *may* be that the aim is, more pedantically, to provide
>    the markup syntax for docstrings *when markup is wanted*.

Added.

>    The start of the document sounds a little, to me, as if it is
>    deprecating plain text as docstring content. Of course, that
>    may just be me.

How a proposal is perceived *is* important.  Best not to start off on
a wrong note.

> 2. The example docstrings are not laid out according to the
>    normal style - for example::
> 
>             class Keeper(Storer):
...
>    doesn't start with a single summary line,

Fixed.

>    and that single summary line (!) isn't on the same line as the
>    opening triple quotes.

I don't see that requirement specified anywhere in the style guide.
My preference is to start multi-line docstrings with triple-quotes on
a separate line.  I've added a sentence to PEP 257 to clarify.

>    Also, I would argue that the first sentence is redundant - it
>    doesn't tell us anything new.

I'm using it to illustrate namespaces.  The entire class is useless,
just a simple example.

> 3. When discussing field lists, I would separate the point about RFC
>    headers (in PEPs) out - it confuses the matter.

Gone.

There's already a note in Goal 5; should be sufficient.

> 4. In the revamped-PEP examples (both "before" and "after"),
>    the text::
> 
>         This PEP proposes a adding frungible doodads

Fixed.

> 5. I note that www.doodads.org claims that frungible.html
>    does not exist.

I shoulda known that *someone* would try out that URL.  And I shoulda
guessed that such a site exists.  I've changed it to
www.frungible-doodads.org.

Is there a URL equivalent of a 555-prefix telephone number?  One
that's guaranteed *not* to exist, therefore safe to use in examples,
movies, and TV shows?

>    Hmm - would it be a good idea to *number* the questions
>    (and answers) - it would make it easier to discuss them
>    (e.g., Q6 and A6 rather than Q and A).

Done.

> 7. Personally, I probably *would* have separated the issue
>    of docstring markup and PEPs, mainly because it makes
>    this PEP longer. But I've been wrong before.

I don't want to be accused of being PEP-happy.  If instructed so by
the powers that be, I'll split it up.

> 8. When the document is finalised, will you also put up a
>    version in reST?

But of course!  I was thinking about writing it *first* in
reStructuredText, then converting it to old-PEP-style.  It would make
a neat project.  But the to-do list grows, and I wanted to get this
out there.

> > Any questions or answers to add to the Q & A?  Any
> > glaring omissions?
> 
> Not that spring to my mind. Oh - except that you don't actually point
> out that this is all *working*, right now and as of this moment.

Done.

And thanks.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net