[asterisk-doc] Application Documentation

[Russell Bryant]

Leif Madsen wrote:
> Very cool! What might we do about being able to keep all of this
> documentation synchronized between the documentation project, and
> Asterisk itself? It might be pretty useful to have a website where
> people can read about the various applications and functions, and for
> that documentation to be in sync with what is show when you do a show
> application <foo>.

I'd like to reiterate the ideas that Mark presented on the conference
call when we were discussion this a couple weeks ago.  The idea was to
track which SVN revision number the documentation is up to date with.
Of course, having the documentation crew look at every single commit to
see if it affects documentation doesn't sound all that appealing.

However, one thing we could probably do is make a policy to put some
kind of tag in the commit messages that indicates that the commit
affects documentation.  Then, we could have a post-commit script that
looks for this tag, and sends the commit to the documentation mailing
list when appropriate.

> It logically seems to make the most sense to use
> DocBook in Asterisk to keep all the documentation centralized
> (end-user documentation of course -- coding documentation is in
> doxygen).

I'm not sure if this is the direction we should take.  However, the real
issue is that the information about the arguments to an application is
not stored in any way that code can automatically figure out what to do
with them.

Essentially, there is a big blob of text that describes all of the
options, which is what you see when you do "show application whatever".
 Then, the code itself in every application manually parses the string
of arguments.  These two things need to be somewhat unified so that the
arguments can be parsed before they make it to the application.  When we
get this cleaned up, the ability to generate documentation at the level
of refinement that we need for this should be solved as a side benefit.

> Suggestions? I think this would be a good topic to put on the
> conference call for next week.

We discussed some of these issues during the first conference call and
agreed that it was something we would revisit after 1.4 is released.
I'd rather reserve the time in the conference calls for things that need
to happen before 1.4 released for now.

Russell