[asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world

[Tzafrir Cohen]

On Tue, Jul 08, 2008 at 06:30:42PM +0200, Michiel van Baak wrote:
> Hi all,
> 
> Olle already mentioned it briefly, but I wanted to devote a whole post
> to it:
> We are currently working on defining and implementing an XML format for
> apps/function/etc documentation.
> 
> The goal of this project is to convert the static documentation in the
> sourcecode into a parseable format that will be loaded at runtime.
> Right now, the apps for example, have a static char description that
> documents all the options etc. This info can only be used inside
> asterisk on the CLI with 'core show application FOO'

It's easy to make it extractable at build time without any major
changes.

See the macros in http://svn.digium.com/view/asterisk/team/tzafrir/docs/
http://svn.digium.com/view/asterisk/team/tzafrir/docs/?view=log

One unrelated thing I learned from there: extracting text from the whole
of the Asterisk source tree is not so expensive. At least if you do it
in a single sed/awk/perl script. The first time may take a bit longer to
get the text in the cache. But the following runs are much faster.

> 
> With this new XML setup we can still do that, but the documentation will
> be structured and parseable.
> One thing that comes to mind is some webbased documentation.
> 
> We defined the format in:
> http://svn.digium.com/view/asterisk/team/group/appdocsxml/doc/xmldocumentation.txt?view=markup
> and the TODO list in:
> http://svn.digium.com/view/asterisk/team/group/appdocsxml/TODO_appdocsxml?view=markup

http://svn.digium.com/svn/asterisk/team/group/appdocsxml/doc/xmldocumentation.txt
http://svn.digium.com/svn/asterisk/team/group/appdocsxml/TODO_appdocsxml

That's the format.

Where is the documentation stored? How is it generated? What about
external modules? What about modules of which an original version exists
in the tree but I load a different version from elsewhere?

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir