[OpenSER-Docs] Doc Improvements

[Edson]

Tag, Henning... :)

Great... I think that this discussion is comming to somewhere...

At least some points are boiling up:
1- the doxygen informations (graphs?) must be re-worked, because they are to
technical, but the soul is there... it must be "fished";
2- until now no kind of this information has been introduced on
documentation. It should be somehow...
3- general overview, in this point are good and enough for me;

So it appears that is all about how to import the right info in an automatic
way. So let's write this in our TODO list (on the wiki site that Daniel
suggested seems to be a good place), and move on with our actual task:
SGML2XML

Edson

>-----Original Message-----
>From: Henning Westerholt [mailto:henning.westerholt at 1und1.de]
>Sent: quarta-feira, 5 de março de 2008 13:51
>To: Edson
>Cc: openser-docs at lists.openser.org
>Subject: Re: [OpenSER-Docs] Doc Improvements
>
>On Wednesday 05 March 2008, Edson wrote:
>> 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).
>
>Hi Edson,
>
>sure, but if nobody bothers to document this stuff it doesn't matter where
>the
>information is missing. The function that is exported from the module to
>the
>config script don't match exactly to the C function that lays behind it. So
>i
>think that showing users that information will only add confusion.
>
>> 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.
>
>Well, its possible to provide general overview pages in doxygen. So it
>would
>be great to have such pages for every module that exports a API that is
>used
>from some other modules, for example. But this is at the moment not
>available.
>
>> 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...
>;)
>
>Sure, for stable releases there will be no major changes. But i don't think
>that its worth all the work at the moment, especially given the state of
>the
>doxygen documentation for now.
>
>Lets look at an example, for the domainpolicy module:
>http://devel.openser.org/doxygen/dir_21e5e54a1f4057cbcc2546fbd3b342f3.html
>
>The information from the dependency graphs are that this modules depends on
>the parser (that is not configurable) and the DB interface. This
>information
>should also stated in the module documentation.
>
>Cheers,
>
>Henning