[Doc-SIG] Approaches to structuring module documentation

[Manuel Gutierrez Algaba]

On Tue, 23 Nov 1999, Paul Prescod wrote:

> Manuel Gutierrez Algaba wrote:
> > 
> > I think we must invent the wheel, or at least improve it. I don't
> > like javadoc, it seems to me very low level ( type-driven ), useful
> > for java, but python deserves a higher level stuff.  
> 
> I don't follow. Perhaps you could give an example. Anyhow, we want to be
> very careful not to stray too far into only accepting a solution that is
> "best" and not the one that is good enough. 

I have had these doubts when working with python: 
- How to do a specific thing ? ( how to get a random number? 
how to get the time?  which module or which builtin function ? )
- If python can do : -1 * ( 3, 5). It can't, although it could
give : (-3, -5). 
- How to inheritate safely ? 
- How to use CGI or Unix related stuff with python ?
- How much memory a construction takes? How the memory is released ?
How to improve speed a bit ? 

Most of my doubts can be resumed into one: The need of "high level
information". I've never needed to know the signature of a function,
or If i needed it , i found it seamlessly. I don't need javadoc,
nor pythondoc, not at all certainly, I can read the .py , which
are more compact than html info of java, usually. 

Lots of people, specially newbies, have the same problem: Doubts
but not about the parameters of a function, ... real BIG DOUBTS! 
I don't care either about the genealogy of any class, if I care, 
I just follow the code! Even TkInter code!

The funny (or sad) thing is that most of the info is available,
 out there,
hidden in nice layouts and documents, spread over USENET, FAQs, 
modules, tutorial....

Imagine that you want to produce html code. Well, I'd go 
to /usr/local/lib/pyt... and then I'd have a glance to htmllib,
well, it's undocumented ! or at least the 1.5.2 version I have,
but that seems a parser, not a writer of html... Well, it happens 
that the StructuredText.py of pythondoc does exactly what I want. 
How could I known that ? Simply marking it with:
\indexhtmlgeneration or something similar. 

Lots and lots of programms and modules perform auxiliary tasks, or
many of their tasks are reusable (  you know , OO programming)
or they have small pieces of info ( examples of UNIX CGI programming,
environment variables, tk, ...).

Well, If that's we want to, why don't we just do it? We have 
only to MARK that small pieces of info. Fred calls this indexing.

Many people, me included, won't accept a method of doc that requires
a sintax or the loss of freedom when doing things ( this includes
docstrings ). But it's acceptable to write python code, and then 
put:
"\indexexamplelambda" or 
"\indexsocket"
because that marking would be useful even for the programmer himself,
even he eventually got accostumed to doc things just writting indexes and
... but that'd be the second and third step. Anyway, most people
won't be angry against such a simple measure. 


I suppose that this is like Parnassus's stuff: put a black background,
some .gif's, and PostGress database and you got a GREAT site. :-P

If Fred thinks that providing a "smart" way of showing how many
modules, functions and expections are in a piece of python code is 
enough,
I think that with that we don't go much further.

Here the Pop SuperStar is "Information" ( brute, massive, overwhelming
info... ). We need just a method of gluing as fast and as simple 
as possible "tons" of info. And that method is indexing ( as brute,
massive and overwhelming as "Information" is).

No traditional parser-driven or XML-driven or javadoc-driven approach
will bear the richness, complexity, diversity of origin/source,
 state,... of so many info. 

BTW: Documenting the python library would be the minor  and less
interesting thing by far. 

We have a Golden Chance here, we can have the best info system
of the Internet. Don't try to be The Big Hero, the Big guy who finds 
the smart solution. Here the Only One Hero is Information, the 
Information that should be at last available !

Indexing for the masses !! Masses of indexes !! Simple and effective!

Death or victory ! 

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

  Just remember, wherever you go, there you are. -- Buckaroo Bonzai