[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[David Abrahams]

----- Original Message -----
From: "Guido van Rossum" <guido@python.org>
To: "David Abrahams" <david.abrahams@rcn.com>
Cc: <python-dev@python.org>
Sent: Saturday, April 06, 2002 1:47 PM
Subject: Re: [Python-Dev] PEP 287: reStructuredText Standard
DocstringFormat


> > 1. 5 more characters just to get started. Probably a shift key too,
if
> > I'm going to be stylistically conformant with other work I've seen.
> > ("""...""").
>
> Depends on how long your comment is going to be.  For long comments, a
> on each line gets boring quickly, and not all editors know how to
> reformat such comment blocks right.

Ah, but /mine/ does <.002wink>. Anyway, I presume docstrings are
supposed to be relatively short?

Note that I am not comfortable just opening the docstring, because then
the editor colors the rest of my program green until I add the closing
quotes, so I have to type six quotes and three "move back"s just to get
started. It takes nine boring lines of documentation to even approach
the labor implied by opening comment characters. Any
single-character-to-end-of-line syntax is going to make things easier.

> > 2. The docstring separates the function signature from its body,
which
> > tends to obscure the code a bit. I prefer prefix documentation.
>
> You have a small point there.

nay, it's bigger than a breadbox.

> Don't do this!  There's an explicit rule that doc strings should be
> indented like the code containing them, and all docstring processors
> are supposed to compensate for this.  Please write this, like
> everybody else does:
>
>     def foo(bar, baz):
>         """Start of doc
>
> rest of doc
> and some more doc"""
>         function_body()

I assume what I'm seeing above is due to the fact that you used the
hated tab key to indent part of the docstring? That wasn't what you
intended, was it? Also, isn't the closing quote supposed to occupy a
separate line?

> Also note the blank line after the first line -- the first line is
> supposed to be a one-line summary of the function (for use in
> abbreviated help balloons, overviews, and so on).

That's what I thought. Is there a guideline for how to write those, BTW?

> > Documentation is really hard to start with, and every additional
> > barrier to entry is unacceptable to me. Every time I write a doc
> > string, I think of all 3 of the above things, which causes a little
> > "cognitive dissonance", and makes it less likely that I'll write
> > another.
>
> Time for you to start reading more Python code -- I've never heard
> this excuse before.

How is reading more Python code going to help? Not trying to be
difficult, really. I'm willing to invest a little to train my stupid
brain to stop complaining. Still wish I didn't have to, though.

-Dave