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

[Tilghman Lesher]

On Friday 11 July 2008 18:05:03 Michiel van Baak wrote:
> On 17:11, Fri 11 Jul 08, Tilghman Lesher wrote:
> > On Friday 11 July 2008 16:07:11 Brandon Kruse wrote:
> > > >----- Original Message -----
> > > >From: "Tzafrir Cohen" <tzafrir.cohen at xorcom.com>
> > > >Suppose the application Foo in our documentation takes no parameters.
> > > >Now I unload the standard module and load a module that includes Foo()
> > > >that has two parameters. When and how will the application metadata in
> > > >Astrisk be invalidated?
> > >
> > > So you are saying you have an app, for example, that registers "Dial",
> > > then you unload app_dial, and load app_thisisstupid.so, which registers
> > > application Dial.
> > >
> > > First of all, I do not see how that would EVER happen, and why you
> > > would want to have such confusion. Second of all, the
> > > app_thisisstupid.so does NOT use ast_register_application_xml, it will
> > > just use
> > > app_register_application, like a normal app.
> > >
> > > If you really wanted to do this (which I, will not), you could have one
> > > app be part of 'core' and one of them be a 'third party app'
> > >
> > > I would hope you would want to have these conflicts figured out before
> > > hand.
> >
> > A very real situation is someone unloading the app_stack.so from 1.4 and
> > loading the app_stack.so module backport from svncommunity.  The backport
> > is desireable, because it has more features.  The documentation and
> > argument syntax both differ.  How would you accommodate this situation?
>
> Good point.
>
> Maybe something like <Application name="Dial" core="yes">
> All stuff in the digium official tree should have this core flag so it
> will read the docs out of core-$lang.xml
> If this is not set, it will try to look for an <Application name="Dial">
> tag in one of the extra xml files in the doc/ directory.
>
> How about that ?

I've already suggested that the documentation be parsed and embedded
directly within the module.  Then there is no confusion whatsoever about which
documention should be sourced, or even if there is documentation at all.  If
it's embedded, there is no confusion.  I realize that means you can't update
it without recompiling, but then again, who really ever does that?

-- 
Tilghman