[asterisk-dev] Syntax for application parameters

[Mark Michelson]

Tilghman Lesher wrote:
> On Tuesday 09 June 2009 09:52:04 Philipp Kempgen wrote:
>> Will schrieb:
>>> On Tue, Jun 9, 2009 at 8:31 AM, Jared Smith<jsmith at digium.com> wrote:
>>>> Eliel and I started a vigorous discussion on the asterisk-dev IRC
>>>> channel earlier today regarding the syntax for application parameters in
>>>> the built-in help, and I'd like to open up the discussion for more
>>>> members of the development community before we agree on a format.
>>>>
>>>> >From what we've discussed this morning, it appears we have four
>>>>
>>>> different proposed versions of the syntax:
>>>>
>>>> 1) Application([param1][,param2[,param3]])
>>>> 2) Application([param1[,param2[,param3]]])
>>>> 3) Application([[param1][,[param2][,[param3]]])
>>>> 4) Application([param1][,[param2][,[param3]]])
>>> #3 looks like it's missing a ] somewhere. Assuming the missing ] is on
>>> the end, #3 and #4 are functionally equivalent (unless I missed
>>> something) and is what I prefer, since it allows parameter index to
>>> stay the same, even if you choose to leave out parameters.  If you
>>> want to leave out a parameter, just put nothing in it's position so
>>> you end up with (param1,,param3).
>> The same goes for #1 and #2 provided the user knows that params can
>> be empty. I get your point but it might not be worth the additional
>> "clutter" in #3 and #4. #1 and #2 are easier to "parse". jm2c
> 
> That assumes that certain parameters are allowed to be empty.  If a parameter
> is required, and the user assumes, according to the syntax, that it can be 
> omitted, that would be considered unclear and thus poor documentation.  This
> is why I favor #4.
> 

The presence of square brackets around the parameter means that it is optional. 
If a parameter is required, then it would not have square brackets around it. 
Therefore a user would know that the parameter could not be omitted.

Can you give an example of what you are talking about?

Mark Michelson