Doxygen Guidelines: @brief for @file?

[Sebastian Huber]

Hello,

I rework currently the Doxygen Guidelines in the RTEMS Software 
Engineering manual. I am not sure what we want to do with the @brief in 
the @file blocks. For me it is important that each file belongs to a 
group, so an @ingroup should be mandatory. With an @ingroup the @brief 
seems to be redundant (the group should have an @brief and a detailed 
description). This is my proposal for the @file blocks:

Files
-----

Place an ``@file`` block at the top of each file.  The ``@file`` block 
should
precede the license header.  This placement reduces the chance of merge
conflicts in imported third-party code.  The ``@file`` block shall be 
put into
a group with ``@ingroup``.  The ``@file`` block shall not have additional
content, e.g. a ``@brief`` description.

.. code:: c

     /**
      * @file
      *
      * @brief RTEMSScoreThread
      */

-- 
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.