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

[Tilghman Lesher]

On Saturday 12 July 2008 04:26:57 Tzafrir Cohen wrote:
> 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?

I'm suggesting that all languages be embedded in the module, none kept
externally.

> 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).

Precisely.  If the data is embedded directly within the module, then there is
no chance of a mismatch.  I think this thread is illustrating nicely just how
ugly, inconvenient, confusing, and problematic external documentation can
be.

-- 
Tilghman