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

[Tilghman Lesher]

On Saturday 12 July 2008 04:07:43 Kaloyan Kovachev wrote:
> 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'.

How does Asterisk know which version to display?  Worse, if there are multiple
competing implementations (as with app_speak), which custom documentation
should be used?

-- 
Tilghman