[Doc-SIG] Documentation tool

[Mark Hammond]

>Hm...  I've read plenty of Java code and have no problem with its
>markup of doc comments.  Perhaps we could reconsider this?

Yay!! :-)

Ive been thinking about this for quite a number of years now - ever
since I started the reference documentation in Pythonwin (which is
getting quite complete!).

I see gendoc as a very useful tool, but IMO targetted at a different
"audience" than the autodoc style of documentation.

The main "features" of autodoc that make it particularly suitable to
"reference" guides is:

* It reorders your input tags.  For example, dispersed through out
your implementation of a single function, you may have comments like
"@see something" and "@see thistoo". These may be intermingled with
other marked up documentation.  When the documentation is produced,
there is a single "See Also" section with all the "@see" references
rendered.
Basically, the format of the output if defined externally, and quite
independent of the input ordering.  This makes for consistent and
professional reference guides.

* Many of the "links" are implicit.  In the example above, a "@see
something" does not require any tags to make it into a hyperlink.
The "@see" tag is defined as taking a single object reference (ie, a
name, not a phrase).  Therefore, autoduck renders the "See Also"
section with Hyperlinks if it can resolve the name, otherwise
renders it it as normal text.

* Hyperlinks may be explicit.  The autodoc I use uses a format <o
objectname> or <om [object.]method>.  Thus you may have a comment
"@comm This is very similar to <om othermethod> but a bit different"
In this case, a "Comments" section will appear in the final output,
and all "@comm" paragraphs rendered there (with tags resolved)

* <a> tags are _not_ used, as there is no way to know the final URL
of anything.  Something like the <a tag _could_ be used for external
Web references, but that is about all.

* Many "@" tags are optional.  Eg, "@parm" tags may be used, but if
they dont exist, autodoc is capable of extracting at least default
info from parsing the C sources.  Obviously Python makes this even
easier.


This is quite different from the goals of gendoc, which to my mind
are more suited to all documentation other then reference guides :-)
gendoc allows you to structure tutorial, or introductory type
material.  It is far far better at this than autodoc.  IMO, the
general structure of autodoc makes for far better reference guides.

Also, I see this fitting beautifully (nearly :-) with gendoc.
gendoc handles the docstrings, and autosnake uses Python comments.

Ahh - so many ideas, so little time :-(

Mark.