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

[Russell Bryant]

Michiel van Baak wrote:
> On 23:52, Tue 08 Jul 08, Jared Smith wrote:
>> 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 agree!  :)

-- 
Russell Bryant
Senior Software Engineer
Open Source Team Lead
Digium, Inc.