[PATCH] eng: Rework and clarify Doxygen Guidelines
Sebastian Huber
sebastian.huber at embedded-brains.de
Thu Nov 19 08:32:35 UTC 2020
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/
More information about the devel
mailing list