[asterisk-dev] [asterisk-commits] russell: trunk r72932 - in /trunk/doc: ast_agi_commands.tex asterisk.tex

[Luigi Rizzo]

On Tue, Jul 03, 2007 at 12:27:29AM +0300, Tzafrir Cohen wrote:
> On Mon, Jul 02, 2007 at 12:52:52PM -0700, Luigi Rizzo wrote:
...
> > I have a few comments on this and related commits:
...
> > 3. I am not sure I understand why the latex is generated through
> >    manager commands. While i may see a reason to do it at runtime,
> >    perhaps because certain commands are dynamically created etc,
> >    I would expect only one command-line switch like
> > 	asterisk --dump-doc [format[:directory]]
> >    which generates the latex and terminates.
> > 	This would make all the completion etc redudant, and simplify
> >    the implementation
> 
> Still, for the build system we need a way to extract the documentation
> of all the AGI commands. Even those currently disabled, right?
...
> 5. The commands dump to a hard-wired file name. Allow declaring a target
>    filename with 'into FILENAME'?
> 
>    It should be the responsibility of the caller to provide a temporary
>    file name and to clean up.
> 
> 6. The SVN now includes the outputs of those commands. But that output
>    depends on the modules you happened to build on your system when you
>    updated the file.

I really think that the way to go is a doxygen-like approach, where
you insert specially annotated comments in the source code that can
then be extracted to produce the documentation (in this case, syntax
and descriptions for manager/cli/agi/younameit commands).

   True, in this case the "documentation" is already stored in C strings
as part of the CLI/etc entries, so doing plain doxygen is not
straightforward, and it might seem more convenient to try and extract
this text at runtime. But in fact i believe it makes things more
complex (because you need to add code to each module) and less
reliable (because you depend on loading all modules in order to
generate a full documentation).

I'd rather address this by placing some restriction on the source
code format, e.g. place markers around the C strings that should
also end up in the documentation, so we can extract that text
without too complex processing.

In any case, it usually helps a lot to
1. write down half a page of text trying to describe what one wants
   to achieve and how/when the feature should be used, and
2. reread it _before_ moving to coding mode.

	cheers
	luigi