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

[Jared Smith]

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.

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>

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.


-- 
Jared Smith
Training Manager
Digium, Inc.