[sr-dev] git:master: - Doxygen updates on core files

[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 at 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=5a03489e539be9a42994533e55026cc7710d131c 
>>>
>>>
>>> Author: oej <oej at edvina.net>
>>> Committer: oej <oej at 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:
>>
>> 1. 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.


>> 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 */
> 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 at lists.sip-router.org
> http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
>

-- 
Daniel-Constantin Mierla
* Kamailio SIP Masterclass, Nov 9-13, 2009, Berlin
* http://www.asipto.com/index.php/sip-router-masterclass/