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

[Russell Bryant]

Tilghman Lesher wrote:
> On Tuesday 08 July 2008 12:29:12 Russell Bryant wrote:
>> Tilghman Lesher wrote:
>>> 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.
>> How would that work for external modules?
> 
> The data is stored in exactly the same place -- inside the module.  The only
> possible difference is that the language stored within the module for the
> documentation could be different.

Well, all languages would have to be stored in the module, then. 
Otherwise, binary distribution of Asterisk would not be able to support 
multiple languages without multiple builds of modules.

I guess I don't really care that much whether it is loaded at run-time, 
or compiled in.

Having it compiled in does increase the complexity quite a bit, I would 
think.

>> Also, keep in mind that this metadata will likely get used for much more
>> than rebuilding the original blog of documentation.  This gives us a
>> step toward being able to do much more advanced dialplan validation at
>> load time.
> 
> I'd be interested to see how you're going to express that grammar within an
> XML file before I make a judgement on that, keeping in mind that some options
> have single arguments, multiple arguments, multiple arguments with alternative
> delimiters, and optional arguments.
> 

Well, when I was proposing the project to these folks, my goal was to 
end up with a format that _does_ express all of that information.  If 
the format doesn't include all of the information that you just 
mentioned, then it's not the ideal format I was looking for, yet.  We 
should be able to get there, though.

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