[rtems commit] cpukit: Use Consistent Beginning of Doxygen Group Notation

[Sebastian Huber]

Hello Joel,

On 01/11/2013 04:00 PM, Joel Sherrill wrote:
> On 01/11/2013 07:49 AM, Sebastian Huber wrote:
>> On 01/11/2013 12:02 AM, Joel Sherrill wrote:
>>> diff --git a/cpukit/include/rtems/irq-extension.h b/cpukit/include/rtems/irq-extension.h
>>> index 644091b..ff2c6da 100644
>>> --- a/cpukit/include/rtems/irq-extension.h
>>> +++ b/cpukit/include/rtems/irq-extension.h
>>> @@ -38,9 +38,8 @@ extern "C" {
>>>     * In addition to the Classic API interrupt handler with a handle are
>>>     * supported.  You can also install multiple shared handler for one interrupt
>>>     * vector.
>>> - *
>>> - * @{
>>>     */
>>> +/**@{**/
>>>
>>>    /**
>>>     * @brief Makes the interrupt handler unique.  Prevents other handler from
>> I think this change should be reversed.  A single @{ without a preceding
>> @defgroup or @addtogroup makes no sense.  Thus is should be also part of the
>> corresponding comment block.
>>
>>
> The inclusion of the opening was inconsistent across the files.
> I saw three patterns and wasn't sure there were not more:
>
> /**@{*/

I prefer this variant:

>
>   * TEXT
>   *
>   * @{
>   */
>
>
>   * TEXT
>   * @{
>   */
>
> I thought it got lost in the comment block and that the single
> line by itself stood out more.

Yes, it stands out more and this is the problem from my point of view.  We have 
the second variant also in the Doxygen recommendations:

http://www.rtems.org/wiki/index.php/Doxygen_Recommendations#Using_.40defgroup_for_group_definitions

> Plus it matches the ending block
> marker. Plus it is what is documented in the Doxygen manual

Yes, it is there, but in the example on this page you see the second variant also.

>
> http://www.star.bnl.gov/public/comp/sofi/doxygen/grouping.html
>
> FWIW the extern C, ending block and inclusion prevention
> stuff at the bottom of the files is also very inconsistent
> in precise formatting.

Yes, FreeBSD uses

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.