[Doc-SIG] Some random thoughts
Peter Funk
pf@artcom-gmbh.de
Mon, 6 Mar 2000 14:45:42 +0100 (MET)
Hi!
Edward Welbourne wrote:
[...about section headings in doc strings...]
> How about a line starting (at the indent of its predecessors) with a
> colon ?
> ... """First line
>
> Introductory paragraph, ...
>
> Arguments:
>
> blah -- desription
>
> : First section
>
> paragraphs indented relative to it
>
> : sub-section
[...]
I don't like this. Why invent something new, when there is natural
and appealing notation available, which is already used several times
within the Python standard library? Have a look at the docstrings
contained in 'cgi.py', 'pipes.py' or 'pprint.py'. Here is an
(shortened) example:
"""
[...]
Using the cgi module
--------------------
[...]
"""
This should be easy to detect and is unlikely to fail.
Regards, Peter
--
Peter Funk, Oldenburger Str.86, D-27777 Ganderkesee, Germany, Fax:+49 4222950260
office: +49 421 20419-0 (ArtCom GmbH, Grazer Str.8, D-28359 Bremen)