[PATCH] eng: Rework and clarify Doxygen Guidelines

[Sebastian Huber]

On 10/11/2020 13:55, Sebastian Huber wrote:

> 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?
>
If nobody objects, then I will commit this on Monday and continue with 
my documentation work.

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