[OpenSER-Devel] Doxygen adoptions

[Henning Westerholt]

On Saturday 31 May 2008, Johansson Olle E wrote:
> I've been working quite a lot with the doxygen docs in Asterisk and
> would like to do some changes to the source files in OpenSER.
>
> In order to get file listings actually show the purpose comment of
> each file and display copyright properly, I would like to add
> a few extra lines in top of each file, like:
>
> /*! \file
>   *
>   * \brief Generic fixup functions for module function parameter.
>   *
>   * Copyright (C) 2001-2003 FhG Fokus
>   * Copyright (C) 2006 Andreas Granig <agranig at linguin.org>
>   *   ( covers insert_path_as_route() )
>   * - \ref ViaSpecialParams
>   */

Hi Olle,

would be great to include this in the files. But do you think its really 
necessary to include the copyright statements also in the doxygen statements? 
This would basically duplicating them, as there are also present on top of 
the GPL header.

> Also standardize on non-javadoc doxygen comments, like
>
> /*! \brief checks if ip is in host(name) and ?host(ip)=name?
>   * ip must be in network byte order!
>   *  resolver = DO_DNS | DO_REV_DNS; if 0 no dns check is made
>   * \return 0 if equal */
>
> Instead of
>
> /**
>   *
>   */

Well, the javadoc format uses '@', if i remember correctly.. The '**' format 
is the one i've choosen for my additions of doxygen to the code, as its most 
similar to the C comment style. Would be nice to have only one syntax that is 
used in the code.

> During a boring flight across Europe, I've made a lot of these changes
> that I can submit if no one protests about these changes.
> It's not complete, but at least changes a lot of the core files so
> that listings of files and functions will use the existing comments
> in the source file. It doesn't change any code, only comments.

I think this would be a good addition.

Cheers,

Henning