[Doc-SIG] Documentation tool

[Robin Friedrich]

> From: John Mitchell <johnm@magnet.com>
> To: Mark Hammond <MHammond@skippinet.com.au>
> 
> > When I suggested something like this a while ago to the DOC SIG, the
> > consensus was that it does not scan well enough for humans.  People
> > thought that the doc strings should be less intrusive than that.
> 
> I dont agree.  I want low-hassle input that makes for pretty output, with
> cross-language support.  "@see" isnt bad, but magic parsing (a la Jim
> Fulton)  doesnt do it for me. 
> 

Having looked at the javadoc man page it seems reasonable.  Much of it
though is unnecessary as pythondoc can infer much from the module
environment. I would say that @see, @return, @param in particular would be
useful for definitively marking the docstring. Structured text, which is
good for paragraph, bullet and heading formation, is lacking when it comes
time to define your parameters. A convention is needed.

I still dislike the idea of placing HTML directly in the body to provide
either markup (<B><I>) or references. (javadoc is way too HTML oriented for
my taste) I like the gendoc standards for this; i.e. **words** and *words*
and the .. href expansions at the bottom. So I guess we would have a mixed
bag but not to the point of irritation.  Is this a good compromise?

-Robin