[OpenSER-Devel] Doxygen updates - developer documentation

[Johansson Olle E]

Hi,

I've spent some time going through the source code of OpenSER svn  
trunk lately, exposing a lot of the source code comments in Doxygen  
format. There's quite a number of files with documentation, but even  
more without, which is unfortunately not surprising in an Open Source  
project. You can see the latest version of the doxygen generated web  
site here:

http://devel.openser.org/doxygen/

I am trying to group files together in modules, you will see that if  
you click on "modules". Each file is given a one-line description,  
including a tag if it belongs to a module. Click on "File list" to see  
a list of all the files (and you will see how many that still lack a  
one-line description).

If I find an interesting multiline explanation, I add that to a  
separate page in doxygen, you will see those if you click on "related  
pages". These are not edited at all and in some cases a bit strange  
since they are out-of-context. The important part is that we start  
collecting what's already in there, then add to it and edit a bit for  
it to make sense in this format.

Having a well structured and informative source code documentation  
helps all. What's even more important, it lowers the barrier for entry  
for new developers, regardless if they want to write a complete new  
module, fix a huge bug or just add a small little feature. Open Source  
projects depend on contributions and I feel that making it easier for  
new members of the community to contribute is important.

While the core developers are busy preparing the new release, I would  
ask other members of the community to assist in this effort. Go  
through files, add doxygen formatting (look into the existing files  
for some hints, or check the manual at http://www.doxygen.org). Create  
a patch and add it to the documentation bug tracker at the OpenSER  
sourceforge page (a link exists on the left hand side of http://www.openser.org 
). You don't have to add information, just start with exposing what we  
already have in the source.

Example:

/* fuzzes permaglotiles heavily, return a pointer to a hermagroxy if  
zwobelut */
function fuzz_perma()
{
    ....
}


Change this  comment to

/*! \brief fuzzes permaglotiles heavily, return a pointer to a  
hermagroxy if zwobelut */

And that comment will be the one-liner that documents this function.  
(The "/*!" is a marker for Doxygen to start parsing the comment).

If you have multiple lines, separate the "brief" one-liner from the  
rest with a blank line, like

/*! \brief fuzzes permaglotiles heavily
  *
*  Return a pointer to a hermagroxy if zwobelut */

To be a bit more doxygen-like, you can mark the result as a result too:

/*! \brief fuzzes permaglotiles heavily
  *
*  \return a pointer to a hermagroxy if zwobelut */


See, it's not that hard!

I'll be on holiday for two weeks now, so I will try to refrain from  
uploading a large set of patches. To keep the flow,
why don't you start? Doxygenification is very easy to do with a small  
amount of your brain power directed towards
a bad DVD on your TV. Just put the laptop in your knee, the can of  
Coke on the table, turn on the film and go.

And if someone asks you about what you thought about the film? Just  
say something clever, like

-"Well, I think Ingmar Bergman's deep exposure of the human side of  
the mantra of enlightment and depression
   was a bit more insightful and related to mankind of today."

...and they won't disturb you any more.

Let's doxygenify OpenSER!

Greetings from a sunny Sweden!

/Olle