Doxygen Guidelines: @brief for @file?

[Sebastian Huber]

On 03/04/2019 15:10, Joel Sherrill wrote:
>
>
> On Wed, Apr 3, 2019 at 3:11 AM Sebastian Huber 
> <sebastian.huber at embedded-brains.de 
> <mailto:sebastian.huber at embedded-brains.de>> wrote:
>
> 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
>       */
>
>
> The @brief shows up in at least the list of files and table of 
> contents when PDF. It should
> be a short English description of the files. I feel STRONGLY that we 
> should have an @brief
> and that it is better English than the example above.
>
> Here is an example in HTML output of where it is used:
>
> http://www.icu-project.org/apiref/icu4c/files.html
>
> FWIW the daily built Doxygen is inaccessible so I can't show you what 
> it looks like in our
> documentation.

We have about 5000 files which should be in a group. I don't want to 
write prosaic text for each file. What about this approach:

/**
  * @file
  *
  * @ingroup RTEMSScoreThread
  *
  * @brief
  *
  * @copybrief 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.