Module: sip-router Branch: master Commit: 5a03489e539be9a42994533e55026cc7710d131c URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5a03489e...
Author: oej oej@edvina.net Committer: oej oej@edvina.net Date: Mon Oct 19 22:35:43 2009 +0200
- Doxygen updates on core files - Add project name to doxygen in Makefile
---
Makefile.rules | 1 + action.c | 1 + action.h | 7 ++ atomic_ops.h | 12 +++- atomic_ops_init.h | 17 +++-- basex.c | 2 +- basex.h | 158 +++++++++++++++++++++++------------------------ bit_scan.h | 32 ++++++---- cfg_core.c | 81 +++++++++++------------- cfg_core.h | 27 +++++--- cfg_parser.c | 102 +++++++++++++++++++------------ cfg_parser.h | 79 +++++++++++++---------- clist.h | 28 ++++++--- compiler_opt.h | 25 +++++--- config.h | 121 ++++++++++++++++-------------------- core_cmd.c | 12 +--- core_cmd.h | 7 ++ crc.c | 14 ++--- daemonize.c | 29 ++++----- daemonize.h | 11 +--- data_lump.c | 11 +--- doc/doxygen/ser.doxygen | 4 +- 22 files changed, 419 insertions(+), 362 deletions(-)
Diff: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commitdiff;h=5a03...
On Oct 19, 2009 at 22:36, Olle E. Johansson oej@edvina.net wrote:
Module: sip-router Branch: master Commit: 5a03489e539be9a42994533e55026cc7710d131c URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5a03489e...
Author: oej oej@edvina.net Committer: oej oej@edvina.net Date: Mon Oct 19 22:35:43 2009 +0200
- Doxygen updates on core files
First of all thanks a lot for the many doxygen updates.
I do have 2 requests though:
1. Could you make sure you don't use lines longer then 79 characters? (some of the comments you modified no longer respect this)
2. Could you (in the future) please use javadoc style for files in the core, tm and files added by me? That means using /** shortdesc . ... instead of /*! \brief shortdesc */
I personally find comments with backslashes hard to read (I cannot read them quickly, I always have a tendency to stop at escaped chars) and they distract me a lot.
Andrei
19 okt 2009 kl. 23.05 skrev Andrei Pelinescu-Onciul:
On Oct 19, 2009 at 22:36, Olle E. Johansson oej@edvina.net wrote:
Module: sip-router Branch: master Commit: 5a03489e539be9a42994533e55026cc7710d131c URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5a03489e...
Author: oej oej@edvina.net Committer: oej oej@edvina.net Date: Mon Oct 19 22:35:43 2009 +0200
- Doxygen updates on core files
First of all thanks a lot for the many doxygen updates.
You're welcome.
I do have 2 requests though:
- Could you make sure you don't use lines longer then 79 characters?
(some of the comments you modified no longer respect this)
I could, but why? (Just curious)
- Could you (in the future) please use javadoc style for files in
the core, tm and files added by me? That means using /** shortdesc . ... instead of /*! \brief shortdesc */
In kamailio, we had /*!
The \brief needs to be there regardless, like \file and all the other doxygen commands.
I think we need *one* standard, regardless of where files are, having one for core, tm and Andrei-files does not make sense to me. I can settle with both /** and /*!, just got used to /*! from Kamailio and Asterisk.
I personally find comments with backslashes hard to read (I cannot read them quickly, I always have a tendency to stop at escaped chars) and they distract me a lot.
All Doxygen commands start with backslashes, so if we're going to use Doxygen, you will have to get used to it. ;-)
/O
Hello,
On 20.10.2009 12:28 Uhr, Olle E. Johansson wrote:
19 okt 2009 kl. 23.05 skrev Andrei Pelinescu-Onciul:
On Oct 19, 2009 at 22:36, Olle E. Johansson oej@edvina.net wrote:
Module: sip-router Branch: master Commit: 5a03489e539be9a42994533e55026cc7710d131c URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5a03489e...
Author: oej oej@edvina.net Committer: oej oej@edvina.net Date: Mon Oct 19 22:35:43 2009 +0200
- Doxygen updates on core files
First of all thanks a lot for the many doxygen updates.
You're welcome.
I do have 2 requests though:
- Could you make sure you don't use lines longer then 79 characters?
(some of the comments you modified no longer respect this)
I could, but why? (Just curious)
this is a general rule, code and comments must not exceed standard terminal -- it was in Kamailio as well, not sure these rules are collected somewhere, but I like to stick to this rule as well.
- Could you (in the future) please use javadoc style for files in
the core, tm and files added by me? That means using /** shortdesc . ... instead of /*! \brief shortdesc */
In kamailio, we had /*!
The \brief needs to be there regardless, like \file and all the other doxygen commands.
I think we need *one* standard, regardless of where files are, having one for core, tm and Andrei-files does not make sense to me. I can settle with both /** and /*!, just got used to /*! from Kamailio and Asterisk.
Another rule is that contributors must obey the format of main developer. For example, I like opening brackets on a new line after if/while/etc. Others want it at the end of line. When adding code to parts not started by me I try to conform the general pattern found in the file. I expect same from the others.
I do not think a general rule must be installed, it is clear devels have different habits, in order to be easy for them to maintain own code, the contributors should follow devel requirements.
Cheers, Daniel
I personally find comments with backslashes hard to read (I cannot read them quickly, I always have a tendency to stop at escaped chars) and they distract me a lot.
All Doxygen commands start with backslashes, so if we're going to use Doxygen, you will have to get used to it. ;-)
/O
sr-dev mailing list sr-dev@lists.sip-router.org http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
20 okt 2009 kl. 13.42 skrev Daniel-Constantin Mierla:
Hello,
On 20.10.2009 12:28 Uhr, Olle E. Johansson wrote:
19 okt 2009 kl. 23.05 skrev Andrei Pelinescu-Onciul:
On Oct 19, 2009 at 22:36, Olle E. Johansson oej@edvina.net wrote:
Module: sip-router Branch: master Commit: 5a03489e539be9a42994533e55026cc7710d131c URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5a03489e...
Author: oej oej@edvina.net Committer: oej oej@edvina.net Date: Mon Oct 19 22:35:43 2009 +0200
- Doxygen updates on core files
First of all thanks a lot for the many doxygen updates.
You're welcome.
I do have 2 requests though:
- Could you make sure you don't use lines longer then 79
characters? (some of the comments you modified no longer respect this)
I could, but why? (Just curious)
this is a general rule, code and comments must not exceed standard terminal -- it was in Kamailio as well, not sure these rules are collected somewhere, but I like to stick to this rule as well.
Ok. Haven't seen a standard terminal for ages, but anyway... :-)
- Could you (in the future) please use javadoc style for files in
the core, tm and files added by me? That means using /** shortdesc . ... instead of /*! \brief shortdesc */
In kamailio, we had /*!
The \brief needs to be there regardless, like \file and all the other doxygen commands.
I think we need *one* standard, regardless of where files are, having one for core, tm and Andrei-files does not make sense to me. I can settle with both /** and /*!, just got used to /*! from Kamailio and Asterisk.
Another rule is that contributors must obey the format of main developer. For example, I like opening brackets on a new line after if/while/etc. Others want it at the end of line. When adding code to parts not started by me I try to conform the general pattern found in the file. I expect same from the others.
In this case, it's requirements made by doxygen that forces us to use backslashes, regardless of what Andrei thinks ;-)
I do not think a general rule must be installed, it is clear devels have different habits, in order to be easy for them to maintain own code, the contributors should follow devel requirements.
It makes it very, very hard for new developers to join the project to not have a common set of coding guidelines. You can't possibly expect everyone to guess or find out how each developer wants their code formatted, nor contribute in eight different code styles, depending upon who originally coded a file.
Having made my protest known, I will of course try.
One thing that should be a requirement is to document the function of each file. There's a lot of files without a single line explanation now, which I personally think is bad. You have to make a guess from the file name, which might or might not work out.
/O
On Oct 20, 2009 at 13:59, Olle E. Johansson oej@edvina.net wrote:
20 okt 2009 kl. 13.42 skrev Daniel-Constantin Mierla:
Hello,
On 20.10.2009 12:28 Uhr, Olle E. Johansson wrote:
19 okt 2009 kl. 23.05 skrev Andrei Pelinescu-Onciul:
On Oct 19, 2009 at 22:36, Olle E. Johansson oej@edvina.net wrote:
Module: sip-router Branch: master Commit: 5a03489e539be9a42994533e55026cc7710d131c URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=5a03489e...
Author: oej oej@edvina.net Committer: oej oej@edvina.net Date: Mon Oct 19 22:35:43 2009 +0200
- Doxygen updates on core files
First of all thanks a lot for the many doxygen updates.
You're welcome.
I do have 2 requests though:
- Could you make sure you don't use lines longer then 79
characters? (some of the comments you modified no longer respect this)
I could, but why? (Just curious)
this is a general rule, code and comments must not exceed standard terminal -- it was in Kamailio as well, not sure these rules are collected somewhere, but I like to stick to this rule as well.
Ok. Haven't seen a standard terminal for ages, but anyway... :-)
You need a limit anyway and since 80 is the standard term. width... 79 allows one extra character, making editing with vi in "list" mode, much nicer. (btw I use standard linux txt consoles for editing some times)
- Could you (in the future) please use javadoc style for files in
the core, tm and files added by me? That means using /** shortdesc . ... instead of /*! \brief shortdesc */
In kamailio, we had /*!
The \brief needs to be there regardless, like \file and all the other doxygen commands.
I think we need *one* standard, regardless of where files are, having one for core, tm and Andrei-files does not make sense to me. I can settle with both /** and /*!, just got used to /*! from Kamailio and Asterisk.
Another rule is that contributors must obey the format of main developer. For example, I like opening brackets on a new line after if/while/etc. Others want it at the end of line. When adding code to parts not started by me I try to conform the general pattern found in the file. I expect same from the others.
In this case, it's requirements made by doxygen that forces us to use backslashes, regardless of what Andrei thinks ;-)
No, it's not. The nice thing about doxygen is that it accepts javadoc style (JAVADOC_AUTOBRIEF should be set to YES in the config) and qt style comments too. Almost all doxygen style tags (or at least the one that are mostly used) have equivalent javadoc tags, e.g.:
Instead of /*! \brief txt ... */ - /** txt. ... */ \param - @param \return - @return \sa - @see *!< - **< \file - @file
I do not think a general rule must be installed, it is clear devels have different habits, in order to be easy for them to maintain own code, the contributors should follow devel requirements.
It makes it very, very hard for new developers to join the project to not have a common set of coding guidelines. You can't possibly expect everyone to guess or find out how each developer wants their code formatted, nor contribute in eight different code styles, depending upon who originally coded a file.
I agree, but good luck enforcing it :-) The set of the coding guidelines is both in the repo: http://git.sip-router.org/cgi-bin/gitweb.cgi?p=sip-router;a=blob;f=doc/ser-c... and on the wiki: https://sip-router.org/wiki/coding_style
Having made my protest known, I will of course try.
One thing that should be a requirement is to document the function of each file. There's a lot of files without a single line explanation now, which I personally think is bad. You have to make a guess from the file name, which might or might not work out.
/O
Andrei
P.S.: just a tip for people who don't know it yet: all the doxygen documentation is auto-generated from the latest code and can be accessed under http://sip-router.org/doxygen/sip-router/branch/master Same goes for modules/core user docs: http://sip-router.org/docbook/sip-router/branch/master/
On Tue, Oct 20, 2009 at 2:34 PM, Andrei Pelinescu-Onciul andrei@iptel.org wrote:
P.S.: just a tip for people who don't know it yet: all the doxygen documentation is auto-generated from the latest code and can be accessed under http://sip-router.org/doxygen/sip-router/branch/master Same goes for modules/core user docs: http://sip-router.org/docbook/sip-router/branch/master/
Just a little side note. The scripts which generate this DO NOT use the doxygen configuration file in sip-router/doc/doxygen. Hence, making changes to the configuration file will not alter the look and feel of the automatically generated documentation.
If you want to re-configure how the auto-generated doxygen documentation looks like, please let me know.
-- Jan
20 okt 2009 kl. 16.48 skrev Jan Janak:
On Tue, Oct 20, 2009 at 2:34 PM, Andrei Pelinescu-Onciul andrei@iptel.org wrote:
P.S.: just a tip for people who don't know it yet: all the doxygen documentation is auto-generated from the latest code and can be accessed under http://sip-router.org/doxygen/sip-router/branch/master Same goes for modules/core user docs: http://sip-router.org/docbook/sip-router/branch/master/
Just a little side note. The scripts which generate this DO NOT use the doxygen configuration file in sip-router/doc/doxygen. Hence, making changes to the configuration file will not alter the look and feel of the automatically generated documentation.
If you want to re-configure how the auto-generated doxygen documentation looks like, please let me know.
Well, the changes I've done in the configuration is that we take a few parameters from the Makefile now, to make sure that we always have the right product name and version in the doxygen documentation. I was looking into including the logo you made too, but that's not a priority.
/O
On Tue, Oct 20, 2009 at 8:09 PM, Olle E. Johansson oej@edvina.net wrote:
20 okt 2009 kl. 16.48 skrev Jan Janak:
On Tue, Oct 20, 2009 at 2:34 PM, Andrei Pelinescu-Onciul andrei@iptel.org wrote:
P.S.: just a tip for people who don't know it yet: all the doxygen documentation is auto-generated from the latest code and can be accessed under http://sip-router.org/doxygen/sip-router/branch/master Same goes for modules/core user docs: http://sip-router.org/docbook/sip-router/branch/master/
Just a little side note. The scripts which generate this DO NOT use the doxygen configuration file in sip-router/doc/doxygen. Hence, making changes to the configuration file will not alter the look and feel of the automatically generated documentation.
If you want to re-configure how the auto-generated doxygen documentation looks like, please let me know.
Well, the changes I've done in the configuration is that we take a few parameters from the Makefile now, to make sure that we always have the right product name and version in the doxygen documentation.
As for name, it should be the neutral "sip-router" in the online documentation. And regarding version, the script which updates online documentation retrieves the current version from the git repository, the result looks like this:
2.99.99-git20091020.f790040
Because we update the online document automatically every 15 minutes or so, the version string includes the git revision so that we could see what commit does the documentation refer to.
I was looking into including the logo you made too, but that's not a priority.
That's a good idea, I'll see what I can do.
-- Jan
- Could you (in the future) please use javadoc style for files in
the core, tm and files added by me? That means using /** shortdesc . ... instead of /*! \brief shortdesc */
In kamailio, we had /*!
The \brief needs to be there regardless, like \file and all the other doxygen commands.
I think we need *one* standard, regardless of where files are, having one for core, tm and Andrei-files does not make sense to me. I can settle with both /** and /*!, just got used to /*! from Kamailio and Asterisk.
Another rule is that contributors must obey the format of main developer. For example, I like opening brackets on a new line after if/while/etc. Others want it at the end of line. When adding code to parts not started by me I try to conform the general pattern found in the file. I expect same from the others.
In this case, it's requirements made by doxygen that forces us to use backslashes, regardless of what Andrei thinks ;-)
No, it's not. The nice thing about doxygen is that it accepts javadoc style (JAVADOC_AUTOBRIEF should be set to YES in the config) and qt style comments too. Almost all doxygen style tags (or at least the one that are mostly used) have equivalent javadoc tags, e.g.:
Instead of /*! \brief txt ... */ - /** txt. ... */ \param - @param \return - @return \sa - @see *!< - **< \file - @file
Well, right. But you still have to use /** @brief
As you dislike using \ I dislike using @ in text... ;-)
Thinking about this stuff, is there a document documenting current maintainers? If there is, I know who to bug for documentation in the code ;-) We do have authors to a lot of files that are no longer contributing because of forks...
/O
-
Andrei Pelinescu-Onciul -
Daniel-Constantin Mierla -
Jan Janak -
Olle E. Johansson