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

[bkruse]

This message is geared towards coming up with a way to access and store 
the documentation,
and not so much the functionality of using the XML to do cool stuff like 
language support, dialplan
validiation, dialplan generation (based on schema), etc.

The proposition:

Have the documentation of the CORE generated xml file (eg all the 
documentation from everything included in build time) be stored in 
/var/lib/asterisk/docs/core.xml.

When a third party module, or any other kind of module is installed 
OTHER than the main checkout, it will be their responsibility to provide 
documentation in the new format, in the right place.

For example, say Cepstral wanted to do a release of their third-party 
module for Asterisk.

They install app_cepstral into /usr/lib/asterisk/modules, then install 
documentation into
the docs directory under extra/ ; The filename does not matter (all will 
be checked), so say:
cepstral.xml. The program checks cepstral.xml, things just work, easy.

Now, what happens if we download a new and awesome improved app_stack, 
that has GosubIf, which
the older app_stack had, but now can have more arguments and functionality?

Easy, the new and improved app_stack installs to 
/usr/lib/asterisk/modules; then puts it's documentation in doc/extra/ 
called app_stack.xml (of whatever the developer wants to call it)

The beauty of this is that app_stack ONLY has to update the GosubIf 
application documentation, because if the documentation is not found in 
the special file (in this case app_stack.xml) then it searches for it in 
core.xml.

Tell me what you think!

-bk