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

[Michiel van Baak]

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
> pseudo-code:
> 
> <parameter name="Technology/Resource" required="true" argsep="&amp;">
>   The technology and resource of the device(s) to attempt to call.
> </parameter>
> <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>
> <parameter name="Options" required="false">
>   <option name="name="A">
>     <argument name="x" required="true">
>       The file to play to the called party
>     </argument>
>     Play an announcement to the called party, using
> <replaceable>x</replaceable> as the name of the file to play
>   </option>
>   <option name="C">
>     Reset the CDR for this call
>   </option>
>   ...
> </parameter>
> <parameter name="URL" required="false">
>   An optional URL that can be sent to the endpoint, if the endpoint
> supports it
> </parameter>

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
http://michiel.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?"