Doxygen Guidelines: @brief for @file?

[Joel Sherrill]

On Wed, Apr 3, 2019 at 8:44 AM Sebastian Huber <
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>> 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.


Now you know why we have been using Doxygen as GCI tasks for years.
More people should mentor GCI to do this type of random, broad clean up.



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

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


>
> --
> 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.
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190403/4af6b8fe/attachment-0002.html>