[asterisk-dev] RFI for AAL; 16 Application Documentation Problems

[Steve Murphy]

Hello--

First of all, this post is in HTML mode, because it is almost totally
unreadable in plain ascii! My 
mail package is in the habit of forcing lines to be less than 80
columns, which destroys the
readability. So please, bear with me.

I'm beginning work on AAL (Asterisk Argument Language)... at least, 
I'm thinking about it. What is that, why should you care about it?
Well, 
my intention is to have it be a formal specification of the arguments
an 
app or function will expect to be passed. AAL will supply functions to 
automatically split the incoming string into the separate arguments,
and 
do argument checking.  It could easily serve as a source for generating 
documentation about the app/function, at least a part of it. It will
also 
allow automatic argument checking to be done at load time, instead 
of at invocation time.

I've got a crude attempt at it in AEL2, but, it's just not right. (See
the applist file).

To get a an idea of what its full scope needs to be, I need to
understand 
all the args of all the apps and funcs. And the descriptions provided
for 
some of them are just PLAIN WRONG.

I've gone thru all 145 apps in the trunk branch. I've done a
 "show application XXXX" for each one, and looked at the argument
 descriptions. To be specific, I was interested in the first line of 
the "[Description]" category. I separated out the apps that 
have problems.

Now, I guess I could file bugs against each problem I outline 
below, but really, that wouldn't be appropriate. In the end, I think 
AAL could replace the document strings I'm pointing out, and 
therefore, the point is not to fix the problems I'm pointing out, but
to 
collect the proper info, and come up with something that will be 
more formal, and correct by design, so speak. 

It would be nice if the experts/authors/heavy users of the below 
apps would respond to the comments I make, affirming my 
assumptions, or correcting them, then I will have some reliable 
info to refer to. Telling me to study the source for 145 apps is not 
a very nice, nor a very practical thing to do!

And, lastly, AAL is definitely an "architectural" thing. Therefore, 
I guess it's a target for 1.5 or 1.6, as I just recently saw that 1.4 i
s architecturally closed...

Now, on to the issues!

First of all, is it completely true that none of the following take any 
arguments? For instance, I KNOW that NoOp is a lie! It takes args 
and it prints them out to the console when it is invoked...


GetCPEID
LookupCIDName
StopPlayTones() 
NBScat
NoOp()
PauseMonitor
StopMonitor
StopMusicOnHold
UnpauseMonitor

Technically, based on convention, in that first line of 
the "[Description]", I'd expect to see something like () 
after the name if the app indeed takes no args. For an 
app like NoOp(), I'd expect it to say "NoOp(rawString)" 
or something. It wasn't super clear that the 9 apps above 
were really argument free, at least not from just reading. 
But, for the purposes of documentation, they should 
be accurate...

For instance, StopPlayTones doesn't follow convention
 at all. All it says is "Stop playing a tone list".  it should 
have a call summary like almost every other app... it 
should at least explicitly state "StopPlayTones()". It might 
also be nice if it explicitly said something like "Will stop 
playing any Tonelist that might be currently playing on 
the current channel."...



Next, AMD: The way the args are written, any of the 
args could simply dropped, along with its separator, 
but this is nonsense! There is no way to tell, if say, 
only one arg is included, which it could be. They all 
seem to be numeric.

AMD([initialSilence][|greeting][|afterGreetingSilence][|
totalAnalysisTime]
      [|minimumWordLength][|betweenWordsSilence][|maximumNumberOfWords]
      [|silenceThreshold])

My GUESS at what the syntax really might be would be more like this:

AMD( [initialSilence] | [greeting]  | [afterGreetingSilence] |
[totalAnalysisTime]
      |  [minimumWordLength]  | [betweenWordsSilence] |
[maximumNumberOfWords]
       | [silenceThreshold] )

Better yet,

AMD( [  [initialSilence] | [greeting]  | [afterGreetingSilence] |
[totalAnalysisTime]
      |  [minimumWordLength]  | [betweenWordsSilence] |
[maximumNumberOfWords]
       | [silenceThreshold]   ]  )

Because I get the feel that if what's in the config file 
is OK, you don't have to supply any args at all. But if 
you just want to override one value, you'd best use 
separators to indicate which one....

Perhaps this might be even more accurate:

AMD( [initialSilence] [ | [greeting]  [ | [afterGreetingSilence]  [  |
[totalAnalysisTime]
      [  |  [minimumWordLength]  [ | [betweenWordsSilence]  [  |
[maximumNumberOfWords]
      [  |  [silenceThreshold]  ] ] ] ] ] ] ]  )

which would allow you to drop any 
trailing "|"'s from after the last non-empty arg...? 
For instance, if you wanted to override JUST the 
"betweenWordsSilence" to 2928, you would write:

AMD(|||||2928)

Which is it really?


Next, the Background app's description:

  Background(filename1[&filename2...]   [ |options [ | langoverride ]
[ | context ]   ] ):

Again, the way it's written, if only one value follows "options", 
is it  langoverride, or context?  Is it really not meant to say:

  Background(filename1[&filename2...] [ | [options]  [ |
[ langoverride ]  [ |  context  ] ] ]  )

Which, if you just wanted to specify a context, with no options 
or override, you would say:

Background(zeeble&Zorkfest||mycontext)

or, just to supply an option, and leave out any trailing | separators:

Background(zeeble&Zorkfest|x)

Am I right?


Next, ControlPlayback:

  ControlPlayback(file[|skipms[|ff[|rew[|stop[|pause[|restart|
options ] ] ] ] ] ] ] )

First of all, there are 6 opening brackets, and 7 closing. 
Next, the options arg is not optional, which 
really doesn't make much sense, and binds it to the 
restart value-- basically, if you specify a restart
value, you MUST supply the options, even if it is empty...

This may be a simple omission, in which case, the spec would be:

  ControlPlayback(file [ | [skipms] [ | [ ff ]  [ |  [rew]  [ |  [ stop]
[ |  [pause]  [ |  [restart]  [ | options ] ] ] ] ] ] ]  )

So, if all you want to do is specify an option, you have to toss 7
separators in front of it.

(And, of course, my insertion of spaces is purely for readability!)



Next, Dial:

  Dial(Technology/resource[&Tech2/resource2...][|timeout][|options][|
URL])

Again, according to this syntax, I could leave out the 
timeout and options, and just specify the URL by saying:

Dial(Zap/1|http://whatever.com/whatever.gif)

or did I just specify a nonsense timeout?

Isn't the syntax really:

  Dial(Technology/resource[&Tech2/resource2...] [ | [timeout ] [ |
[ options ]  [  | URL ] ] ] ) 



Next, Read:

  Read(variable[|filename][|maxdigits][|option][|attempts][|timeout])

Again, since the separator is included with each 
optional arg, you can drop any of them, and
there's no practical way of telling which is which. 
This can't be right, so perhaps the real syntax is:

  Read(variable [ |  [filename ]  [ | [ maxdigits ]  [ | [ option ]  [ |
[ attempts ]  [ | timeout ]  ]  ] ] ] )

So, if all you want to do is specify a timeout, then it would be:

  Read(x|||||15)

And if just specify a filename, it would be:

  Read(bigfile)


Next, RxFAX:

  RxFAX(filename[|caller][|debug])

Same sort of complaint as in previous apps... if 
just one of caller or debug is stated, how
can the app tell which it is?

The real syntax is perhaps:

  RxFAX(filename [ | [caller ] [ | debug ] ] )



And, lastly, for now, SMS:

  SMS(name|[a][s])

Now, this seems like either or both the letters a and s 
 could appear after the name argument.
Are these not options, and should be specified as
 such (as nearly every other app has, even when
 there's only one of them)?





-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.digium.com/pipermail/asterisk-dev/attachments/20060331/954403ac/attachment.htm