[asterisk-dev] Syntax for application parameters

[Tilghman Lesher]

On Tuesday 09 June 2009 10:58:48 Mark Michelson wrote:
> 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?

A good example would be the L option of the Dial command.  The first parameter
is required, the second and third are optional.  However, if the third option
is specified, then the second option is mandatory.  Thus, the fields are not
all exclusively optional, but rather one option's specification mandates the
specification of another.  You need the proper inclusion of square brackets to
make the documentation clear.

-- 
Tilghman