[Doc-SIG] More documentation

[Jack Jansen]

I get more and more confused as I see the postings of last week come
by. In my mind docstrings have always been intended as quick-and-dirty 
reference information, to be presented (along with function signatures 
and such) when you press a "help" button in a Python IDE. But the way
Moshe's proposals and examples go are much more toward a
tangle/web/weave system, where the source code and the full
documentation are intertwined.

At least, in my mind the examples are all far too verbose: lots of
formatting info, typing info on the variables/functions/exceptions
used, etc.

I know that for me this will not work. Not only do I abhor weave-like
systems (I think writing real documentation should be done with a
completely different mindset, and not sort-of in-between while writing 
the code) but I'm also sure to forget the syntax, so after staring at
the opening """ for a few seconds I'll think "ah, forget it. Who needs 
docs anyway".

The scheme we seemed to be converging to before the conference was
much more to my liking: basically free-format with a few readable
flag-words like "arguments:" or so.
--
Jack Jansen             | ++++ stop the execution of Mumia Abu-Jamal ++++
Jack.Jansen@oratrix.com | ++++ if you agree copy these lines to your sig ++++
www.oratrix.nl/~jack    | see http://www.xs4all.nl/~tank/spg-l/sigaction.htm