[asterisk-dev] Command Syntax -- weird?

[Peter Beckman]

On Mon, 24 Apr 2006, Tzafrir Cohen wrote:

> On Sun, Apr 23, 2006 at 11:15:42PM -0400, Peter Beckman wrote:
>> On Sun, 23 Apr 2006, Russell Bryant wrote:
>>
>>> Peter Beckman wrote:
>>>> The fact that flags to voicemail (though you point
>>>> out that his is changing - sweet!) are part of the mailbox# string is
>>>> confusing when the Dial flags are a comma delimited part of the
>>>> parameters.
>>>
>>> Actually, the options string to Voicemail was moved to the end even before
>>> Asterisk 1.2 was released five months ago.  In fact, this change was made
>>> on
>>> April 13th, 2005 - revision 5461 (we're currently on revision 22230).
>>> That was
>>> over one year ago!
>>>
>>> So, perhaps before you make posts to the development list pointing out
>>> problems,
>>> you should check to see that your statements are still accurate, and not
>>> more
>>> than a year out of date.
>>
>>  I normally would!  Where's that documentation?
>
> You seem to have missed the obvious:

  I seem to have missed it again.. :-)  What do you mean?

  The point I'm trying to make is that Asterisk has almost no web-based
  documentation for the end user that is generated by a group directly or
  closely associated with the development team.  Yes, "show application xxx"
  exists and is always the most up to date, I understand that.  I'm trying
  to annotate that documentation even further to make understanding and
  using Asterisk even easier than it is now.

>>  I found this: http://www.asterisk.org/doxygen/app__voicemail_8c.html
>>
>>  But I can't really find the options for Voicemail in that 1MB file.  By
>>  doing a "show application voicemail" and searching for "This application
>>  allows" I did find it in line 338 of app_voicemail.c.
>
> Hmmm... so you need a small driver that will extract and format the
> usage details from all the applications?

  I can write that, or it can be done by hand.  The issue at hand is that
  the 1 paragraph documentation that lives only within the code and is
  accessible only when running asterisk (or if you know where doxygen is and
  that it exists)  is simply not enough.  If it was enough, sites like
  voip-info.org wiki wouldn't exist -- they wouldn't need to.

  Please understand that I'm not trying to attack developers or try and
  force them to write more documentation.  I'm a developer and I hate
  documenting my own code: "Can't you just read it?  It's self
  documenting!!!"   :-)

  Well, unfortunately code is a horrible thing to read, regardless of how
  well one names their variables and formats their structures.  The developers
  job and talent lies in the code that is Asterisk.

  My purpose here is to make Asterisk better by enhancing and filling out
  the documentation that allows people to quickly understand all of the
  caveats, changes, and functionality of Asterisk, as well as working
  examples that show how they work in a real dialplan.

  I think Asterisk is great!!!

>>  I believe most people who do not develop Asterisk and who don't know about
>>  the "show application xxx" command (and while they should, they don't)
>
> People should know about that. If you're trying to write dialplans, you
> should know about that. If you think that the current CLI of Asterisk is
> not "accissible" enough, write a different front-end.

  I did:

     http://mph.gotdns.com:82/manual/en/function.voicemail.php

> It need only connect to Asterisk via a unix-domain socket or via the
> manager interface and doesn't necessarily have to be part of the Asterisk
> binary.

  I too think it would be horrible to try and make this documentation part
  of the Asterisk binary!

  All I'm asking for is a little welcome access into the developer world.  I
  can read the Change logs, and I can read the code, but having someone,
  such as yourself, let me know that "As of 1.4, Voicemail return code
  FAILED now also occurs when the user enters a DTMF that is not 0 or *."

  That way I can document the changes between versions, and a single piece
  of web-based documentation can serve to document an Application throughout
  the Asterisk development.

Beckman
---------------------------------------------------------------------------
Peter Beckman                                                  Internet Guy
beckman at purplecow.com                             http://www.purplecow.com/
---------------------------------------------------------------------------