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

[Russell Bryant]

Tilghman Lesher wrote:
> I think you misunderstood the concept.  Initially, in the source, the
> documentation is held in some format.  It may be XML, it might be
> something else.  At compile/link time, the documentation (for all languages)
> will be loaded into the object file format, either embedded as strings within
> the data section, or embedded into its own section within the object file.
> For documentation that is queried during the Asterisk runtime, it will be
> accessed directly from this module.  In other words, when it comes to
> "core show application Foo", very little changes from the current method.
> There is no XML to be parsed; the text is simply displayed.  The only big
> change will be that the documentation embedded into the module may be
> in multiple languages.

My one objection here is that you refer to the documentation being 
embedded into the module at compile time.  That would be fine if the 
_only_ thing this information would be useful for is the output of "core 
show application foo".

One of my design goals with this is to have all of the information about 
arguments and options be available in such a way that it could be used 
in other parts of Asterisk.  If this information ends up as a big text 
blob in the compiled module, then I feel like we have only accomplished 
half of the battle.

If it's embedded in the module, then fine, but it should be in the form 
of intelligent data structures.  I think the easiest way to accomplish 
this is to have the XML itself available at runtime in some form or 
another.

-- 
Russell Bryant
Senior Software Engineer
Open Source Team Lead
Digium, Inc.