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

Tzafrir Cohen tzafrir.cohen at xorcom.com
Sat Jul 12 04:26:57 CDT 2008


On Fri, Jul 11, 2008 at 10:30:59PM -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?

If you have a docuemntation for the module in English (embedded in the
module) and in Greek (from the intalled translation) and your language
is Greek, which one do you use?

For messages to the user? For validation?

If we have validation as a goal, we should plan the data ahead, so 1.8
(or 1.6.3) won't break the format (or worse: be stuck with a bad
format).

-- 
               Tzafrir Cohen
icq#16849755              jabber:tzafrir.cohen at xorcom.com
+972-50-7952406           mailto:tzafrir.cohen at xorcom.com
http://www.xorcom.com  iax:guest at local.xorcom.com/tzafrir



More information about the asterisk-dev mailing list