[PATCH] eng: Rework and clarify Doxygen Guidelines

Thu Nov 19 16:28:20 UTC 2020

OK.I must have been remembering some old Doxygen stuff. I first used it
20 years ago and I am sure plenty has changed over the years.

Is there guidance on embedding figures? dot, plantuml, mscgen? I don't
recall if there are actual graphic images embedded. But if there are, we
should have source in some acceptable open format.

On Thu, Nov 19, 2020 at 2:32 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> 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/
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20201119/75c14c1d/attachment.html>