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

[Manuel Gutierrez Algaba]

On Mon, 7 Feb 2000, Peter Funk wrote:
> Hi!
> 
> 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.

Common sense!


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

Literate programming is not dead. We should think too if we 
can develop better tools for handling python code than editors.
Class browsers and such. 
Rich docstrings are interesting but not for functions or classes,
perhaps at the beginning of modules.

> 
> 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.

Another great deal of common sense.

Regards/Saludos
Manolo
www.ctv.es/USERS/irmina    /TeEncontreX.html   /texpython.htm
/pyttex.htm

  I just got out of the hospital after a speed reading accident. I hit a bookmark. -- Steven Wright