[OpenSER-Devel] Doxygen adoptions

[Bogdan-Andrei Iancu]

Guys,

let's keep the doc changes for after the SVN freeze - there is some work 
on progress and we should try to avoid any SVN conflicts (merging 
errors). Once the SVN is frozen (for the C code), we can start playing 
around with the comments format.

Thanks,
Bogdan

Henning Westerholt wrote:
> 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
>
>
> _______________________________________________
> Devel mailing list
> Devel at lists.openser.org
> http://lists.openser.org/cgi-bin/mailman/listinfo/devel
>
>