[OpenSER-Docs] Doc Improvements

[Edson]

Morgen, Henning...

About Your concerns, I'd answer "yes and no"... I agree that this are
tecnichal information and are generated in an "automatic" way (Doxygen)... I
also know how usefull it can be to an advanced user who whats/need to know
what a especific function will do. Only to defend this point, last week (or
so) there was a discussion on IRC where Ovidus rose a point that was not
covered by the documentation and also nos stated on Doxygen: what changes
where introduced by a function on the SIP-Message or on the internal
parameters (like timers, PV, etc).

Getting back on what You wrote, I also agree that this kind of information
don't belong to a README file, but since this is the only module
documentation available nowadays, sorry, but, where should this information
belong to? Where should they be defined?

In my modest oppinion, the README, even thinked as an user introduction doc,
is today the best point to insert this kind of information. In a strutured
way, for sure.

Another consideration is that You say that Doxygen changes, but I think that
this is valid only for trunk version. Stable ones are more immutable. So the
inter-dependence graphs could be inserted (not in TXT version, but in HTML,
PDF, etc). But if You asked me how to integrate them, I have to be honest
and say that just know I really don't know... I can figure that in DOCs
compilation, Doxigen has to be runned, but that's another story... ;)

Edson

>-----Original Message-----
>From: Henning Westerholt [mailto:henning.westerholt at 1und1.de]
>Sent: quarta-feira, 5 de março de 2008 08:29
>To: openser-docs at lists.openser.org
>Cc: Edson
>Subject: Re: [OpenSER-Docs] Doc Improvements
>
>On Tuesday 04 March 2008, Edson wrote:
>> Should the DOC volume include the Doxigen documentation? Where? In a hole
>> dedicated and separete chapter, or should each module have in it's
>> documentation another chapter/section just for dealing with this internal
>> informations? I, particularly would like to see the generated graphs
>being
>> merged just after the function/parameter explanation (just for the
>> external/exported functions/parameters/variables).
>
>Hi Edson,
>
>i think for the moment its better to concentrate on the user visible part
>of
>the documentation, not to start to much at once.. :-) I personally don't
>think that developer informations have a good place in the module READMEs,
>they should be integrated into the doxygen docs. Doxygen is generated
>directly from the source, if we maintain the API informations in another
>place it will be get quickly out of date.
>
>Do you think that this generated graphs are really helpful for normal users
>understanding the functionality that this module provides? I think they are
>perhaps to technical, providing to much details.
>
>Cheers,
>
>Henning