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

[Tony J Ibbs (Tibs)]

Great stuff. Some minor nitpicking (really, that's all it is).

BTW - I haven't copied to Barry Warsaw - please feel free to forward it
explicitly if you feel he needs to follow the details!

1. It *may* be that the aim is, more pedantically, to provide
   the markup syntax for docstrings *when markup is wanted*.

   That is: clearly plain text is always going to be legitimate
   docstring content, and certainly for the near future this will
   be the default. Thus markup is an alternative.

   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.

2. The example docstrings are not laid out according to the
   normal style - for example::

            class Keeper(Storer):

              """
              Extend `Storer`.  Class attribute `instances`
              keeps track of the number of `Keeper` objects
              instantiated.
              """

   doesn't start with a single summary line, and that single summary
   line (!) isn't on the same line as the opening triple quotes.

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

   A better comment would be more like::

            """A useful jacket for lists. (well, OK, one might quibble!)

            The class attribute `instances` is used to keep track
            of the number of `Keeper` objects instantiated.
            """

   (I believe that that layout follows the style guide better, and if
   we're trying to push a PEP, that's a good idea.)

   This comment obviously applies to the other docstrings as well.

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

   Strictly speaking, dealing with RFC headers is an extension, and
*that*
   is reasonable enough, but being able to deal with PEPs is only an
   optional aim, so we shouldn't let it "muddy the water" too much in
   the summary.

   Perhaps something more like::

      Standard RFC822 header syntax cannot be used for this construct
      because it is ambiguous.  A word followed by a colon at the
      beginning of a line is common in written text.

          :Note: If this proposal is accepted for representation
          of PEPs, then a PEP-specific extension would be added
          to allow standard RFC822 header syntax in the first
          "block" of the document. This is a sufficiently well-
          defined context that such support would not be a
          problem.

   Or even move the "note" stuff into the question about support
   for PEPs later on in the docment, possibly with a cross reference
   to it from here.

4. In the revamped-PEP examples (both "before" and "after"),
   the text::

        This PEP proposes a adding frungible doodads

   should (I assume) be::

        This PEP proposes adding frungible doodads

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

6. I was just thinking about the "should markup and PEPs
   be separate" question when you addressed it (!). So
   that's a good thing.

   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).

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.

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

Oh - I guess I should address your *specific* questions!

> Any chance at consensus?

I sincerely hope so - certainly none of my points are (so far as I'm
concerned) things to stop it going forwards.

> Do the "docstring format goals" truly reflect the goals
> of the group?

I think they're one good version of them.

> 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.

(erm - well, your bits anyway. Since we've got my parent's-in-law
visiting, I've even begun work on pydps again, though)

Tibs
--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Give a pedant an inch and they'll take 25.4mm
(once they've established you're talking a post-1959 inch, of course)
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)