[asterisk-dev] Command Syntax -- weird?

[Tzafrir Cohen]

On Sat, Apr 22, 2006 at 11:53:30PM -0400, Peter Beckman wrote:
> On Sat, 22 Apr 2006, Tzafrir Cohen wrote:
> 
> >http://www.asterisk.org/doxygen/ is the documentation that is generated
> >from the code of Asterisk . If you want your documentation to be
> >maintained with the evolution of the code, it has to be there (in the
> >doxygen docs, that is).
> 
>  From the title of the Doxygen page: Developer Documentation.
> 
>  Doxygen is great for developers, but many people who use Asterisk have no
>  interest in .c and .h files!

Right. But people who do the changes happen to write .c and .h files and
not really care about everything else. Certainly not any external
documentation body.

> 
>  What I'm hoping is that the work I'm doing with the Asterisk user
>  documentation is that the developers can focus on writing the code and
>  making it work, and the people in charge of documentation can get a
>  "Change Log" from the developers on the changes, and the doc folk can
>  either look at the code, or look at the Doxygen documentation, and turn it
>  into valuable, end-user documentation.
> 
>  I have no interest in putting documentation into code.  I do, however,
>  think that the "show application Dial" documentation can be confusing due
>  to the lack of consistency between functions.  Having documentation online
>  that is in-step with the Asterisk code is vital, IMO.

Can you suggest an improvement? Consider that any change in the syntax
can break existing dialplans of people, and thus has to be done
carefully.

The framework you put looks useful. However I fear that if the base
won't get updated from the code, it will get "rotten".

-- 
Tzafrir Cohen      sip:tzafrir at local.xorcom.com
icq#16849755       iax:tzafrir at local.xorcom.com
+972-50-7952406           
tzafrir.cohen at xorcom.com  http://www.xorcom.com