[asterisk-dev] XML documentation of apps/functions/the_rest_of_the_world

[Kevin P. Fleming]

Michiel van Baak wrote:

> The way and format we put back into the sourcefiles is subject to
> change, based on input here.
> I'm not sure what the best way to do it is:
> - struct
> - list
> - astobj2

You can't modify the source files at all during the process. At most you
can generate a header file and then forcibly include it with -include in
the CFLAGS for the module. There wouldn't be any value in using
reference counted objects (astobj2) for this as it would be read-only
static data. Storage method is open to debate, but it would be fairly
easy to make arrays containing the data in a header file and the compile
it in. However, keep in mind that this parsing process will have to
happen every time the module is compiled (because the docs could have
changed), which will slow down compiles for developers working on the code.

I would prefer to see the data stored in the module using *no formatting
whatsoever*, so that whatever output method is going to be used can
attempt to format it properly. What we have today, with hard-coded line
breaks at very short lines, is just silly, because it wraps
unnecessarily early on wide consoles.

-- 
Kevin P. Fleming
Director of Software Technologies
Digium, Inc. - "The Genuine Asterisk Experience" (TM)