M.Z. assumptions (was Re: [Doc-SIG] Re: Ease of use is #1)

Peter Funk pf@artcom-gmbh.de
Mon, 7 Feb 2000 14:14:18 +0100 (MET)


Moshe Zadka wrote:
> Assumption 1:
> 	doc-strings should be flexible enough to document most Python
> 	modules without any OOL documentation (that is, as I understand,
> 	our majority vote). The "most" comes because it shouldn't
> 	necessarily be flexible enough to write the reference manual for
> 	the debugger.

I see:  IMHO this first assumption is wrong.  Good reference
documentation often requires complex material like tables, figures,
formulas and more text, which will clutter up the source and distract
during code maintainance.

What you describe is the literate programming approach, which IMHO
has always failed in the past. (Look at TeXs tangle and weave).

It should be possible to autogenerate *some* kind of reference
documentation from doc-strings during early stages of the lifetime
of software.  Later, when the software becomes more mature and
complex, it should be possible to use this autogenerated material
as a starting point for more elaborate documentation.  So not all
features, which would be available at the higher XML level and
which you see used in the current python library reference need to
have a counterpart in an upcoming doc-string grammar.

Regards, Peter
Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60