[PATCH] eng: Rework and clarify Doxygen Guidelines

[Sebastian Huber]

Hello Joel,

On 09/11/2020 15:37, Sebastian Huber wrote:
> 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.
>
do you still have issues with this change?

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