Doxygen Guidelines: @brief for @file?

[Sebastian Huber]

On 03/04/2019 15:48, Joel Sherrill wrote:
>
>
> On Wed, Apr 3, 2019 at 8:44 AM Sebastian Huber 
> <sebastian.huber at embedded-brains.de 
> <mailto:sebastian.huber at embedded-brains.de>> wrote:
>
>     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>
>     > <mailto:sebastian.huber at embedded-brains.de
>     <mailto:sebastian.huber at embedded-brains.de>>> wrote:
>     >
>
[...]
>
>     What about this approach:
>
>     /**
>       * @file
>       *
>       * @ingroup RTEMSScoreThread
>       *
>       * @brief
>       *
>       * @copybrief RTEMSScoreThread
>       */
>
>
> This is OK as a default but it shouldn't be the only option. I 
> wouldn't delete
> a comment that was more specific or use that when a more specific
> comment is better.
>
> We don't want comments to exist just to improve a comments to code ratio.
> They are supposed to be meaningful. IMO the copybrief adds no value to
> the file when reading it.

The file path, file name and @ingroup gives you already a good 
indication to which area a file belongs.

> It only adds value when the file is processed and
> you are reading the Doxygen output. So use this as a default but don't
> delete @brief's which are better and this does not stop someone from
> writing a more meaningful brief.

What about this:

Files
-----

Each source or header file shall have an ``@file`` block at the top of the
file.  The ``@file`` block should precede the license header separated 
by one
blank line.  This placement reduces the chance of merge conflicts in 
imported
third-party code.  The ``@file`` block shall be put into a group with
``@ingroup GroupName``.  The ``@file`` block should have an ``@brief``
description and a detailed description if it is considered helpful. Use
``@brief @copybrief GroupName`` as a default to copy the ``@brief`` 
description
from the corresponding group and omit the detailed description.

.. code:: c

     /**
      * @file
      *
      * @ingroup RTEMSScoreThread
      *
      * @brief @copybrief RTEMSScoreThread
      */

.. code:: c

     /**
      * @file
      *
      * @ingroup RTEMSScoreThread
      *
      * @brief Some helpful brief description.
      *
      * Some helpful detailed description.
      */

Unclear:

Should the @brief in Title Case or should it be a normal sentence?

Some hints what helpful is would be nice. What is the threshold to write 
something special?

>
> I still don't know where in the output, text beyond the @brief on a file
> block goes. Any ideas?

It goes to the "Detailed Description" of the file documentation.

https://docs.rtems.org/doxygen/branches/master/score_2thread_8h.html#details

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