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

[Tilghman Lesher]

On Tuesday 08 July 2008 12:32:09 Michiel van Baak wrote:
> On 12:22, Tue 08 Jul 08, Tilghman Lesher wrote:
> > On Tuesday 08 July 2008 11:30:42 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'
> >
> > XML is fine for documentation, but I'd prefer to see it parsed at build
> > time, not at runtime.  There is no good reason to shift that parsing to
> > runtime.
>
> It's loaded at the same place where the *descrip for an application is
> loaded right now.
>
> This way we only have the documentation loaded for the applications and
> function that are actually loaded into asterisk.
> For example, I dont need the MeetMe documentation loaded when app_meetme
> is not loaded (because of no dahdi for example)

Right, it could get stored in exactly the same place as it is stored now 
(within the module), but it is parsed earlier, instead of forcing all
documentation to exist in an XML file, whether the application is loaded from
modules.conf or not.  This will ease the load on embedded systems, for
example, where adding to the tasks that need to occur at startup time is not
a welcome addition.  It also ensures that we're not adding another large block
of code to systems where space is at a premium.

> Maybe because I'm not a native english speaker there is some confusion.
> The whole documentation.xml is generated on build time.
> The module that is loaded by the loader will grab it's documentation
> from this file.
>
> If you want the details, have a look at ast_register_application2 in
> main/pbx.c

-- 
Tilghman