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

[Tilghman Lesher]

On Tuesday 15 July 2008 07:46:33 Russell Bryant wrote:
> 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.

I'm primarily concerned about the documentation itself, at this stage.  The
material which concerns syntax of commands has yet to be developed, and
so it's not really able to be debated in a meaningful way at this time.  When
we have a proposal before us, we can review the decision.  But it's premature
to make any such decision at this time.

-- 
Tilghman