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

[Michiel van Baak]

On 09:22, Mon 14 Jul 08, Kevin P. Fleming wrote:
> Russell Bryant wrote:
> 
> > Sounds good.  Of course, if anyone else has any proposals on the  
> > mechanics of doing this, please propose them here.
> 
> I can't comment on the construction or the parsing of the data, but it
> would be relatively straightforward to embed the documentation at link
> time into the module in special section(s), named appropriately for the
> language they represent. I'll have to research what the simplest way to
> get access to this data would be, but it's certainly possible.

bkruse and me have been talking about this on IRC.

Here's the gist of our story:

How about we keep the english /*** DOCUMENTATION <xml here> ***/ in the
sourcefiles. This blob will be the english documentation in the xml
format we have documented.

The awk foo that extracts this will be kept as well, so we will have a
doc/core-en.xml generated for us.

We ditch the xml parsing in main/pbx.c (where we register the
application/function/etc on load time) in favor of....

On build/link time we parse the core-en.xml and any translation, and
remove the /*** DOCUMENTATION ***/ block with some C code.
This C code can be a struct with the available documentation in all
available languages.
It can even be (and I prefer this) some C code to make some astobj2's
with the code. This way we can use the astobj2 code to loop through it
on run time when someone uses 'core show application foo'
This way we can change the language on run time, and still have all the
info in a manageble way in the sources.

This will also give us the docs in an xml file for external programs
(php, python, docbook, whatever)

Some pro's I see:
- one way to document apps/functions/etc in a format we have a spec for
- Parseable format outside and inside asterisk. Can be used for dialplan
  validation, external docs, TFOT 3 and later, etc etc
- A big part of the work we have now can be reused
- Documentation embedded in the modules, so no worries when we load
  external modules

The way and format we put back into the sourcefiles is subject to
change, based on input here.
I'm not sure what the best way to do it is:
- struct
- list
- astobj2

Let me know what you think.
-- 

Michiel van Baak
michiel at vanbaak.eu
http://michiel.vanbaak.eu
GnuPG key: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x71C946BD

"Why is it drug addicts and computer aficionados are both called users?"