[Doc-SIG] Documentation tool

[John Mitchell]

On Sat, 20 Jun 1998, Mark Hammond wrote:

> >> I dont know what [JavaDoc formatting is like].  Is it possible to
> >> summarize?
> >
> >Yep. You start a comment with "/**" (instead of "/*", and add in a
> few
> >magic tags.  As in:
> 
> This is almost identical to "autodoc", the tool I wrote about before
> to the SWIG List (Ive suggested that SWIG generate this sort of
> documentation directly in the sources).

woo-woo!  After getting nary a hit w/ Python.org's search engine, I found
"doc.py version 0.8" at http://starship.skyport.net/~lemburg/Software.html
 Is this what you're talking about? 

Doesnt seem to handle any javadoc-isms, like @see... 

So, where's "autodoc" at?


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


- j