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.hu...@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.hu...@embedded-brains.de > >>> <mailto:sebastian.hu...@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.hu...@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/ > >
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel