[asterisk-dev] Command Syntax -- weird?

[Tilghman Lesher]

On Friday 21 April 2006 22:34, Peter Beckman wrote:
> Is there any reason why Asterisk has chosen such strange and
> inconsistent methods of passing variables to functions?

Understanding the history will probably open your eyes.

> VoiceMail([flags]boxnumber[@context][&boxnumber2[@context]][&boxnum
>ber3])

The initial syntax for Voicemail was Voicemail([flags]boxnumber).
That's it.  There was no context and no multiple mailboxes.  The
first thing that was added was a context.  So that's simple enough:
Voicemail([flags]boxnumber[@context]).  From there, we added multiple
mailboxes, which is how we have the current syntax.  Please note that
the flags have already been moved to the end for the 1.4 release,
although flags at the beginning are still accepted for backwards
compatibility.

>      Goto([[context|]extension|]priority)

It's always been this way, and it will likely always be this way.  I
don't see a commanding reason why it ought to change, when any such
reason must balance against backwards compatibility.

> RetryDial(announce|sleep|loops|Technology/resource[&Technology2/res
>ource2...[|timeout[|options[|URL]]]])

RetryDial was based upon Dial.  The developer of that app chose to
prefix the arguments to the Dial command, rather than to add them as
suffixes.  I can't say I necessarily agree with this approach, but
it's over and done now.  In any case, since it's a distinct dialplan
application, it's not nearly that bad.

> Something where every time I specify the first parameter, I always
> know what it is.  Currently if I add on things to Goto, the first
> parameter could be a priority, an extension or a context.  Who
> knows!  Sure, obviously you can tell, but I guess I'm asking why!

As above, it's always been that way, and there hasn't been an
overriding reason to change it.

> BTW, the only reason this really has become clear is because I'm
> working on PHP-like documentation for Asterisk.  OK, I just stole
> what PHP did and made it for Asterisk.  I'm not nearly done, but
> the framework is there for review:
>
>      http://mph.gotdns.com:82/manual/en/index.php
>
> The lack of consistency in function attributes makes it more
> difficult to document!

First of all, I would encourage you to work with the current Asterisk
Documentation Project, rather than to duplicate efforts.  Obviously,
you've already found http://www.asteriskdocs.org, as your current
content is a duplicate of that page.

Second, what you're calling function attributes are actually
application arguments.  Using consistent language in documentation
is one of the keys to making sure your audience doesn't get more
confused, at worst, and understands, at best.

-- 
Tilghman