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

[Russell Bryant]

Luigi Rizzo wrote:
> 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).

The more I think about it, the more I agree that a "doxygen-like"
approach is the right one to take.  While it is extremely tempting to
write code in Asterisk to dump this documentation at runtime, it is
going to be near impossible to have it be complete.

> 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.

I'll divert my efforts to coming up with reasonable ways to do this,
instead.

-- 
Russell Bryant
Software Engineer
Digium, Inc.