On 03/04/2019 15:10, Joel Sherrill wrote:
On Wed, Apr 3, 2019 at 3:11 AM Sebastian Huber
<sebastian.hu...@embedded-brains.de
<mailto:sebastian.hu...@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.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
