[Asterisk-Users] Asterisk Documentation

[Daniel.Sloan at vu.edu.au]

I've spent the last couple of days learning Doxygen and getting at least
basically familiar with the Asterisk source code.  I'm starting to write
up comments for Doxygen to generate API docs from, and I've also started
looking at ways to use Doxygen to generate a configuration reference with
configuration examples, and some 'how to' guides like 'how to write an
application' and 'how to write a channel driver'.

I've seen many other people talk about doing documentation for Asterisk -
most of it seems to have fallen by the wayside for one reason or another.
Doxygen is a nice documentation tool, and with the right sort of comments
in the code, it generates excellent API documentation, in PDF, HTML, CHM,
RTF/DOC, MAN, and Latex formats.  For website docs, it has a search 
engine facility, and its appearance is to some degree customizable.
You can include images, code snippets, graphs, and so on.

My plan of attack is as follows:
1. Develop a better 'progdocs' target that will build a variety of
formats in probably two sections - Developers Reference and Users Ref.
The Developers Reference would be the API docs with some howtos and so
on for writing modules, etc.  The Users Reference would be the config
reference and guides, and some howtos on setting up a * server.  Both
would be at least partly or mostly sourced from structured commenting
in the source code.

2. Start with writing a section in the Developers Reference on "How to
use Doxygen to document * code" :-)

3. If its possible, it would be really great to have the docs hosted on
the Asterisk website.  Might also be pretty cool to have a cron that
regularly checks out the CVS, and does a documentation build, generating
the HTML to update the website docs (at least until Asterisk reaches
a version number with more than a 0 at the beginning :-).
If it can be hosted at asterisk.org, great.  If not, I'll find somewhere
else for it.

4. Improve code commenting where I understand it in Asterisk.

5. Get other people to improve code commenting where I don't.

Does anybody have any thoughts on this plan, or better ideas?
Negative/positive thoughts about Doxygen?
Most importantly, is anyone else working on something along these lines
already?

Cheers.