4 Mar
2008
4 Mar
'08
5:16 p.m.
I know that just now we are dealing with SGML to XML conversion, but it
seams that some point have to be registered:
1- clearer documentation/explanation of the functions internals.
Specifically what they do and what they changes (SIP messages, internal
counters/timers, PV, AVP, etc).
2- make very clear which functions break normal script execution (p.ex. see
the "noisy_ctimer" parameter in TM module" discussion).
And to close a question:
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).
Edson.
4 Mar
4 Mar
6:30 p.m.
Hello,
you rose good points, however, from past experience, the discussions on
mailing list don't get that much compiled and applied, if results won't
be easily accessible. Therefore, I created a dokuwiki page and put there
some requirements for writing documentation for modules. Please add your
points there. In this way we can refer very easy and try to enforce :-) .
http://www.openser.org/dokuwiki/doku.php/doc-devel:module-doc
Thanks,
Daniel
On 03/04/08 18:16, Edson wrote:
I know that just now we are dealing with SGML to XML
conversion, but it
seams that some point have to be registered:
1- clearer documentation/explanation of the functions internals.
Specifically what they do and what they changes (SIP messages, internal
counters/timers, PV, AVP, etc).
2- make very clear which functions break normal script execution (p.ex. see
the "noisy_ctimer" parameter in TM module" discussion).
And to close a question:
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).
Edson.
_______________________________________________
Openser-docs mailing list
Openser-docs(a)lists.openser.org
http://lists.openser.org/cgi-bin/mailman/listinfo/openser-docs
5 Mar
5 Mar
12:28 p.m.
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
1:53 p.m.
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@1und1.de]
Sent: quarta-feira, 5 de março de 2008 08:29
To: openser-docs(a)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
5:50 p.m.
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
5:58 p.m.
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@1und1.de]
Sent: quarta-feira, 5 de março de 2008 13:51
To: Edson
Cc: openser-docs(a)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
5904
days inactive
5905
days old
5 comments
3 participants
participants (3)
-
Daniel-Constantin Mierla -
Edson -
Henning Westerholt