language lawyering - doc strings

[Tony J Ibbs (Tibs)]

gcash wrote:
> I know this is being pedantic, but where's the syntactical spec for
> documentation strings in the language reference?

Hmm - docstrings are just that - strings - so one is allowed to put
whatever text one likes in there, and I believe this will always be the
case. This is a Good Thing, notwithstanding my next points...

There are some basic guidelines on dosctring layout, laid out by Guido
himself, in his style guide:

	http://www.python.org/doc/essays/styleguide.html

which has since evolved into a series of PEPs. In particular,

	http://python.sourceforge.net/peps/pep-0257.html

(still a draft) is relevant.

The Doc-SIG has been working for a long time (!) on producing a spec for
the syntax of docstrings, such that one can parse them (for various
possible reasons). The latest and current work is documented at:

	http://docstring.sourceforge.net/
and	http://structuredtext.sourceforge.net/

The relevant PEPs are numbers 256, 257, 258 (257 was mentioned above, of
course).

There's a draft quick reference at:

	http://structuredtext.sourceforge.net/docs/quickref.html

Some of us have already started to use reST in our docstrings, in
anticipation.

> I was looking at the 2.1.1 docs and I'd expect it to be in "4.1 Code
> blocks, execution frames, and namespaces" but the only reference to
> documentation strings is where it mentions the __doc__ attribute.

Hmm - I wouldn't expect such a peripheral matter (which it is, really)
to be in such a fundamental place.

> I noticed this when someone asserted you can't have doc strings for
> classes.

Interesting. But wrong.

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"Bounce with the bunny. Strut with the duck.
 Spin with the chickens now - CLUCK CLUCK CLUCK!"
BARNYARD DANCE! by Sandra Boynton
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)