[Doc-SIG] Some random thoughts

[Peter Funk]

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)