On 03/04/2019 15:48, Joel Sherrill wrote:
On Wed, Apr 3, 2019 at 8:44 AM Sebastian Huber
<sebastian.hu...@embedded-brains.de
<mailto:sebastian.hu...@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.hu...@embedded-brains.de
<mailto:sebastian.hu...@embedded-brains.de>
> <mailto:sebastian.hu...@embedded-brains.de
<mailto:sebastian.hu...@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.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
