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

Andrei Pelinescu-Onciul andrei at iptel.org
Tue Oct 20 14:34:47 CEST 2009


On Oct 20, 2009 at 13:59, Olle E. Johansson <oej at 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 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.
> 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)

> >
> >
> >>>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.
> 
> 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-coding-style.txt;h=5a2d2;hb=HEAD
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/



More information about the sr-dev mailing list