3 Jan
2015
3 Jan
'15
11:19 a.m.
Hello,
On 03/01/15 11:28, Olle E. Johansson wrote:
Hi!
While going through the core files, I noted that some of the history messages - typically
the first line or two - has important information about the content of the file, which is
not always copied into the Doxygen.
Each file should have a doxygen declaration, like:
/*!
* \file
* \brief Kamailio core :: <description of this file>
* \ingroup core
* Module: \ref core
*/
Please make sure that you preserve the file information. You can add a few lines of
description that you find elsewhere
to the block, like:
/*!
* \file
* \brief Kamailio core :: Gnurging the smorifians
* The smorifians are dangerous parts of a SIP message and needs to be gnurged. This
* code file handles 94.25% of these cases. If you find out how to complete the process,
* please add new functions.
* \ingroup core
* Module: \ref core
*/
You may also add
* \author Gonzilla the IIIrd, emperor of GowarkiStania
<gonzilla(a)gowarkistania.skrep>
I think this is better placed in the AUTHORS file (in root folder),
because over the time authors can change or there can be many, so the
source code will get again a long list, with many values not actual (and
misleading again).
Perhaps we can add an new field to the credits, like M: where to list
the modules the developer has authored or done significant work. Example:
N: Andrei Pelinescu - Onciul
C: andrei
E: andrei(a)iptel.org
P: 2CF56A2D D96D 8B80 BA31 9B93 6208 5D68 3910 FA00 2CF5 6A2D
D:
M: core, tm, ...
Also, the author should be reflected in the readme of the module.
For the code, we should rely on git blame for whenever we need to know
the author of a piece of code, rather than hardcoded annotations in
comments. I would keep the comments only to describe the code.
Cheers,
Daniel
To this section if you find an author or multiple ones.
Doxygen for Kamailio is generated here:
http://sip-router.org/doxygen/sip-router/branch/master/
I did also change any text saying "ser" or "sip-router" to
"Kamailio" while I was in the file changing
text in comments.
Doxygen is cool and very helpful for new developers that wants to find their way
around Kamailio source code.
/Olle
_______________________________________________
sr-dev mailing list
sr-dev(a)lists.sip-router.org
http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
--
Daniel-Constantin Mierla
http://twitter.com/#!/miconda - http://www.linkedin.com/in/miconda