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

[Kaloyan Kovachev]

On Fri, 11 Jul 2008 22:30:59 -0500, Tilghman Lesher wrote
> 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?
> 

What about having embeded in the module doc name and version and later look in
the docs folder for ${name}_${version}_${lang}.xml? We then may have version
1.6.0 with the options for 1.6.0 and later when in 1.6.1 there are new options
(but the module is still compatible) loading the new module will come with
it's own docs. The version should be changed only when the docs are changed
(1.6.8 may still use 1.6.0 docs) and if 1.6.1 is missing older minor version
(1.6.0) may be used instead, but will issue a warning.
If the app is not from core, but localy modified or some other place the name
could be used like 'myCustom-Dial_1.6.0.34_en.xml'.

just my 0.02

> -- 
> Tilghman
> 
> _______________________________________________
> --Bandwidth and Colocation Provided by http://www.api-digital.com--
> 
> AstriCon 2008 - September 22 - 25 Phoenix, Arizona
> Register Now: http://www.astricon.net
> 
> asterisk-dev mailing list
> To UNSUBSCRIBE or update options visit:
>    http://lists.digium.com/mailman/listinfo/asterisk-dev