[asterisk-dev] Syntax for application parameters

[Tilghman Lesher]

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.

-- 
Tilghman