On 09/11/2020 15:12, Joel Sherrill wrote:
On Mon, Nov 9, 2020 at 8:02 AM Sebastian Huber
<sebastian.hu...@embedded-brains.de
<mailto:sebastian.hu...@embedded-brains.de>> wrote:
---
eng/coding-doxygen.rst | 210
++++++++++++++++++++++++++++------------
eng/coding-file-hdr.rst | 2 +
2 files changed, 149 insertions(+), 63 deletions(-)
diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst
index f4308ef..b2e6b61 100644
--- a/eng/coding-doxygen.rst
+++ b/eng/coding-doxygen.rst
@@ -16,12 +16,13 @@ In the RTEMS source code, CamelCase is rarely
used, so this makes it easier to
search and replace Doxygen groups. It avoids ambiguous references to
functions, types, defines, macros, and groups. All groups shall
have an
``RTEMS`` prefix. This makes it possible to include the RTEMS
files with
-Doxygen comments in a larger project without name conflicts.
+Doxygen comments in a larger project without name conflicts. The
group name
+shall use `Title Case
<https://en.wikipedia.org/wiki/Letter_case#Title_Case
<https://en.wikipedia.org/wiki/Letter_case#Title_Case>>`_.
.. code:: c
/**
- * @defgroup RTEMSScoreThread
+ * @defgroup RTEMSScoreThread Thread Handler
*
* @ingrop RTEMSScore
*
@@ -36,18 +37,28 @@ global variable declaration shall belong to at
least one Doxygen group. Use
``@defgroup`` and ``@addtogroup`` with ``@{`` and ``@}`` brackets
to add
members to a group. A group shall be defined at most once. Each
group shall
be documented with an ``@brief`` description and an optional detailed
-description. The ``@brief`` description shall use
-`Title Case <https://en.wikipedia.org/wiki/Letter_case#Title_Case
<https://en.wikipedia.org/wiki/Letter_case#Title_Case>>`_.
-Use grammatically correct sentences for the detailed descriptions.
+description. Use grammatically correct sentences for the
``@brief`` and
+detailed descriptions.
+
+For the ``@brief`` description use phrases like this:
+
+* This group contains ... and so on.
+
+* The XYZ Handler provides ... and so on.
+
+* The ABC Component contains ... and so on.
I don't know where the idea @brief should be short sentences came from.
I reviewed the Doxgyen HTML and PDF output and come to the conclusion
that the use of Title Case makes no sense for the brief descriptions.
@brief is used to make table of contents type pages and those should
read more like titles than the first sentence of the detailed description.
https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html
<https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html>
That Doxgyen removes a trailing '.' from the brief descriptions is a bug
or feature. I didn't find a corresponding view in the PDF.
If you look at the PDF, it really is used for the Table of Contents and
a sentence is quite odd there.
It should read like a chapter title
I looked at the PDF output and the brief descriptions are not included
in the table of contents. The group names are included in the table of
contents. For the group names Title Case should be used. The brief
descriptions are the first sentence of the module description. This is
identical to the HTML output.
Please have a look at:
https://ftp.rtems.org/pub/rtems/people/sebh/refman.pdf
https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/group__ClassicEvent.html#details
You also have the autobrief options which use the first line (until the
first dot) as the brief description.
--
embedded brains GmbH
Sebastian HUBER
Dornierstr. 4
82178 Puchheim
Germany
email: sebastian.hu...@embedded-brains.de
Phone: +49-89-18 94 741 - 16
Fax: +49-89-18 94 741 - 08
PGP: Public key available on request.
embedded brains GmbH
Registergericht: Amtsgericht München
Registernummer: HRB 157899
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler
Unsere Datenschutzerklärung finden Sie hier:
https://embedded-brains.de/datenschutzerklaerung/
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
