[asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world
Michiel van Baak
michiel at vanbaak.info
Wed Jul 9 02:32:56 CDT 2008
On 23:52, Tue 08 Jul 08, Jared Smith wrote:
> On Tue, 2008-07-08 at 18:30 +0200, Michiel van Baak wrote:
> > We are currently working on defining and implementing an XML format
> > for apps/function/etc documentation.
> I'm very happy to see work on this project finally progressing, as I've
> been pushing for something like this for a couple of years now. (Yes,
> that also means I've flapped my jaw for a couple of years and not done
> anything about it myself.)
> Just a few comments on what I'm seeing so far:
> 1) With regards to the XML schema, I just want to make sure that
> everyone is OK with adding tags like <replaceable> and <variable> inside
> the <description> tags. (We can obviously choose different names --
> those are just tags I commonly use in DocBook while writing
> documentation for Asterisk, and it would be nice to not have to
> re-invent the wheel here.
I dont think this will be a problem.
For me it's ok to add those.
Can you give me some more info about what those two tags do ?
> 2) I think we need to carefully decide when to use the <option> tag
> versus when to use the <argument> tag. In the current documentation in
> app_dial.c for example, you've got the first application parameter
> (Technology/Resource) as an <option> node, don't document the timeout
> parameter at all, have all the possible values of the options parameter
> as <option> tags as well, and then have the URL parameter as an option.
> I'd rather see the parameter list look something like the following
> <parameter name="Technology/Resource" required="true" argsep="&">
> The technology and resource of the device(s) to attempt to call.
> <parameter name="Timeout" required="false">
> The number of seconds to let the phone ring before continuing on to
> the next priority in the current extension
> <parameter name="Options" required="false">
> <option name="name="A">
> <argument name="x" required="true">
> The file to play to the called party
> Play an announcement to the called party, using
> <replaceable>x</replaceable> as the name of the file to play
> <option name="C">
> Reset the CDR for this call
> <parameter name="URL" required="false">
> An optional URL that can be sent to the endpoint, if the endpoint
> supports it
at least this is more consistent.
If others agree, I'll update the docs and app_dial.c
> I'll take another look at this as soon as I can make some time over the
> next few days. If it helps at all, I'd be happy to post a more complete
> example, as well as the DocBook source of a few applications from the
> O'Reilly book.
Michiel van Baak
michiel at vanbaak.eu
GnuPG key: http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x71C946BD
"Why is it drug addicts and computer aficionados are both called users?"
More information about the asterisk-dev