[PATCH] eng: Rework and clarify Doxygen Guidelines

[Sebastian Huber]

On 09/11/2020 15:12, Joel Sherrill wrote:

> On Mon, Nov 9, 2020 at 8:02 AM Sebastian Huber 
> <sebastian.huber at embedded-brains.de 
> <mailto:sebastian.huber at 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.huber at 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/