<div dir="ltr">OK.I must have been remembering some old Doxygen stuff. I first used it <div>20 years ago and I am sure plenty has changed over the years.</div><div><br></div><div>Is there guidance on embedding figures? dot, plantuml, mscgen? I don't</div><div>recall if there are actual graphic images embedded. But if there are, we</div><div>should have source in some acceptable open format.</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Nov 19, 2020 at 2:32 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 10/11/2020 13:55, Sebastian Huber wrote:<br>
<br>
> Hello Joel,<br>
><br>
> On 09/11/2020 15:37, Sebastian Huber wrote:<br>
>> On 09/11/2020 15:12, Joel Sherrill wrote:<br>
>><br>
>>> On Mon, Nov 9, 2020 at 8:02 AM Sebastian Huber <br>
>>> <<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a> <br>
>>> <mailto:<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a>>> wrote:<br>
>>><br>
>>> ---<br>
>>> eng/coding-doxygen.rst | 210<br>
>>> ++++++++++++++++++++++++++++------------<br>
>>> eng/coding-file-hdr.rst | 2 +<br>
>>> 2 files changed, 149 insertions(+), 63 deletions(-)<br>
>>><br>
>>> diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst<br>
>>> index f4308ef..b2e6b61 100644<br>
>>> --- a/eng/coding-doxygen.rst<br>
>>> +++ b/eng/coding-doxygen.rst<br>
>>> @@ -16,12 +16,13 @@ In the RTEMS source code, CamelCase is rarely<br>
>>> used, so this makes it easier to<br>
>>> search and replace Doxygen groups. It avoids ambiguous <br>
>>> references to<br>
>>> functions, types, defines, macros, and groups. All groups shall<br>
>>> have an<br>
>>> ``RTEMS`` prefix. This makes it possible to include the RTEMS<br>
>>> files with<br>
>>> -Doxygen comments in a larger project without name conflicts.<br>
>>> +Doxygen comments in a larger project without name conflicts. The<br>
>>> group name<br>
>>> +shall use `Title Case<br>
>>> <<a href="https://en.wikipedia.org/wiki/Letter_case#Title_Case" rel="noreferrer" target="_blank">https://en.wikipedia.org/wiki/Letter_case#Title_Case</a><br>
>>> <<a href="https://en.wikipedia.org/wiki/Letter_case#Title_Case" rel="noreferrer" target="_blank">https://en.wikipedia.org/wiki/Letter_case#Title_Case</a>>>`_.<br>
>>><br>
>>> .. code:: c<br>
>>><br>
>>> /**<br>
>>> - * @defgroup RTEMSScoreThread<br>
>>> + * @defgroup RTEMSScoreThread Thread Handler<br>
>>> *<br>
>>> * @ingrop RTEMSScore<br>
>>> *<br>
>>> @@ -36,18 +37,28 @@ global variable declaration shall belong to at<br>
>>> least one Doxygen group. Use<br>
>>> ``@defgroup`` and ``@addtogroup`` with ``@{`` and ``@}`` brackets<br>
>>> to add<br>
>>> members to a group. A group shall be defined at most once. Each<br>
>>> group shall<br>
>>> be documented with an ``@brief`` description and an optional <br>
>>> detailed<br>
>>> -description. The ``@brief`` description shall use<br>
>>> -`Title Case <<a href="https://en.wikipedia.org/wiki/Letter_case#Title_Case" rel="noreferrer" target="_blank">https://en.wikipedia.org/wiki/Letter_case#Title_Case</a><br>
>>> <<a href="https://en.wikipedia.org/wiki/Letter_case#Title_Case" rel="noreferrer" target="_blank">https://en.wikipedia.org/wiki/Letter_case#Title_Case</a>>>`_.<br>
>>> -Use grammatically correct sentences for the detailed descriptions.<br>
>>> +description. Use grammatically correct sentences for the<br>
>>> ``@brief`` and<br>
>>> +detailed descriptions.<br>
>>> +<br>
>>> +For the ``@brief`` description use phrases like this:<br>
>>> +<br>
>>> +* This group contains ... and so on.<br>
>>> +<br>
>>> +* The XYZ Handler provides ... and so on.<br>
>>> +<br>
>>> +* The ABC Component contains ... and so on.<br>
>>><br>
>>><br>
>>> I don't know where the idea @brief should be short sentences came from.<br>
>> I reviewed the Doxgyen HTML and PDF output and come to the conclusion <br>
>> that the use of Title Case makes no sense for the brief descriptions.<br>
>>> @brief is used to make table of contents type pages and those should<br>
>>> read more like titles than the first sentence of the detailed <br>
>>> description.<br>
>>><br>
>>> <a href="https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html" rel="noreferrer" target="_blank">https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html</a> <br>
>>> <<a href="https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html" rel="noreferrer" target="_blank">https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/modules.html</a>> <br>
>>><br>
>> That Doxgyen removes a trailing '.' from the brief descriptions is a <br>
>> bug or feature. I didn't find a corresponding view in the PDF.<br>
>>><br>
>>> If you look at the PDF, it really is used for the Table of Contents and<br>
>>> a sentence is quite odd there.<br>
>>><br>
>>> It should read like a chapter title<br>
>><br>
>> I looked at the PDF output and the brief descriptions are not <br>
>> included in the table of contents. The group names are included in <br>
>> the table of contents. For the group names Title Case should be used. <br>
>> The brief descriptions are the first sentence of the module <br>
>> description. This is identical to the HTML output.<br>
>><br>
>> Please have a look at:<br>
>><br>
>> <a href="https://ftp.rtems.org/pub/rtems/people/sebh/refman.pdf" rel="noreferrer" target="_blank">https://ftp.rtems.org/pub/rtems/people/sebh/refman.pdf</a><br>
>><br>
>> <a href="https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/group__ClassicEvent.html#details" rel="noreferrer" target="_blank">https://ftp.rtems.org/pub/rtems/releases/5/5.1/docs/html/doxygen/group__ClassicEvent.html#details</a> <br>
>><br>
>><br>
>> You also have the autobrief options which use the first line (until <br>
>> the first dot) as the brief description.<br>
>><br>
> do you still have issues with this change?<br>
><br>
If nobody objects, then I will commit this on Monday and continue with <br>
my documentation work.<br>
<br>
-- <br>
embedded brains GmbH<br>
Sebastian HUBER<br>
Dornierstr. 4<br>
82178 Puchheim<br>
Germany<br>
email: <a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a><br>
Phone: +49-89-18 94 741 - 16<br>
Fax: +49-89-18 94 741 - 08<br>
PGP: Public key available on request.<br>
<br>
embedded brains GmbH<br>
Registergericht: Amtsgericht München<br>
Registernummer: HRB 157899<br>
Vertretungsberechtigte Geschäftsführer: Peter Rasmussen, Thomas Dörfler<br>
Unsere Datenschutzerklärung finden Sie hier: <a href="https://embedded-brains.de/datenschutzerklaerung/" rel="noreferrer" target="_blank">https://embedded-brains.de/datenschutzerklaerung/</a><br>
<br>
</blockquote></div>