[sr-dev] Code clean up - history and svn $id$

[Daniel-Constantin Mierla]

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 at 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 at 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 at 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