<div dir="ltr"><div>Part of this is pushed.</div><div><br></div><div>I made a sweep at coding-doxygen.rst before this arrived. Please see if I missed anything. If so, send a new patch.</div><div><br></div><div>THanks.<br></div></div><br><div class="gmail_quote"><div dir="ltr">On Tue, Dec 4, 2018 at 11:30 AM Marçal Comajoan Cara <<a href="mailto:mcomajoancara@gmail.com">mcomajoancara@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Converted <a href="https://devel.rtems.org/wiki/Developer/Coding/Doxygen" rel="noreferrer" target="_blank">https://devel.rtems.org/wiki/Developer/Coding/Doxygen</a><br>
to Rest, and TBDs and wiki TODOs into comments. Also added formattings, updated<br>
links to Header File Examples and updated the Script Example to include<br>
<a href="https://devel.rtems.org/newticket" rel="noreferrer" target="_blank">https://devel.rtems.org/newticket</a> instead of <a href="http://www.rtems.org/bugzilla" rel="noreferrer" target="_blank">http://www.rtems.org/bugzilla</a>,<br>
which is the old RTEMS Ticket System which may generate confusion.<br>
<br>
Added a label at the beginning of eng/coding-file-hdr.rst to be able to<br>
link the page from eng/coding-doxygen.rst.<br>
<br>
This work was part of GCI 2018.<br>
---<br>
 eng/coding-doxygen.rst  | 475 +++++++++++++++++++++++++++++++++++++++-<br>
 eng/coding-file-hdr.rst |   1 +<br>
 2 files changed, 474 insertions(+), 2 deletions(-)<br>
<br>
diff --git a/eng/coding-doxygen.rst b/eng/coding-doxygen.rst<br>
index 5aafde0..6f98eed 100644<br>
--- a/eng/coding-doxygen.rst<br>
+++ b/eng/coding-doxygen.rst<br>
@@ -6,5 +6,476 @@<br>
 General Doxygen Recommentations<br>
 ===============================<br>
<br>
-TBD - Convert the following to Rest and insert into this file<br>
-TBD - <a href="https://devel.rtems.org/wiki/Developer/Coding/Doxygen" rel="noreferrer" target="_blank">https://devel.rtems.org/wiki/Developer/Coding/Doxygen</a><br>
+.. COMMENT: TBD - Convert the following to Rest and insert into this file<br>
+.. COMMENT: TBD - <a href="https://devel.rtems.org/wiki/Developer/Coding/Doxygen" rel="noreferrer" target="_blank">https://devel.rtems.org/wiki/Developer/Coding/Doxygen</a><br>
+<br>
+Doxygen Best Practices<br>
+----------------------<br>
+<br>
+* Do not use ``@a``. Instead use ``@param`` to document function parameters.<br>
+* Do not use ``@return``. Instead use ``@retval`` to document return status<br>
+  codes.<br>
+* Do not write documentation for trivial functions.<br>
+* Do not repeat documentation, use ``@see`` for example.<br>
+* Do not use ``@note``.<br>
+* Use groups and arrange them in a hierarchy. Put every file into at least<br>
+  one group.<br>
+* Use dot comments for state diagrams.<br>
+* Use one whitespace character after an asterisk. <br>
+<br>
+Special Notes for Google Code-in Students<br>
+-----------------------------------------<br>
+<br>
+Follow the directions given by the `Google Code-in<br>
+<<a href="https://devel.rtems.org/wiki/GCI" rel="noreferrer" target="_blank">https://devel.rtems.org/wiki/GCI</a>>`_ task and this should take<br>
+care of itself if in doubt ask a mentor and/or tell a mentor the decision you<br>
+made.<br>
+<br>
+Header File Example<br>
+-------------------<br>
+<br>
+`thread.h<br>
+<<a href="https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/thread.h" rel="noreferrer" target="_blank">https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/thread.h</a>>`_ and<br>
+`threadimpl.h<br>
+<<a href="https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/threadimpl.h" rel="noreferrer" target="_blank">https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/threadimpl.h</a>>`_<br>
+should be a good example of how a header file shouldbe written. The following<br>
+gives details in bits and pieces.<br>
+<br>
+Header blocks<br>
+-------------<br>
+<br>
+Header files should contain the similar comment blocks as other source files,<br>
+described at :ref:`coding-file-hdr`.<br>
+<br>
+.. code-block:: c<br>
+<br>
+  /**<br>
+  * @file<br>
+  *<br>
+  * @ingroup FlipFlop<br>
+  *<br>
+  * @brief Flip-Flop API<br>
+  */<br>
+<br>
+  /*<br>
+  * Copyright (c) YYYY Author.<br>
+  *<br>
+  * The license and distribution terms for this file may be<br>
+  * found in the file LICENSE in this distribution or at<br>
+  * <a href="http://www.rtems.com/license/LICENSE" rel="noreferrer" target="_blank">http://www.rtems.com/license/LICENSE</a>.<br>
+  */<br>
+<br>
+Header guard<br>
+------------<br>
+<br>
+After the comment blocks, use a header guard that assembles at least the<br>
+include path of the file. For example, if ``flipflop.h`` is in<br>
+``<rtems/lib/flipflop.h>`` then<br>
+<br>
+.. code-block:: c<br>
+<br>
+  #ifndef RTEMS_LIB_FLIP_FLOP_H<br>
+  #define RTEMS_LIB_FLIP_FLOP_H<br>
+<br>
+Includes<br>
+--------<br>
+<br>
+Then add your include files before protecting C declarations from C++.<br>
+<br>
+.. code-block:: c<br>
+<br>
+  #include <rtems.h><br>
+<br>
+  #ifdef __cplusplus<br>
+  extern "C" {<br>
+  #endif /* __cplusplus */<br>
+<br>
+Using @defgroup for group definitions<br>
+-------------------------------------<br>
+<br>
+Add any group definitions surrounding the function declarations that belong<br>
+in that group. Rarely, a header may define more than one group. Here we use<br>
+a dot diagram. <br>
+<br>
+.. code-block:: c<br>
+<br>
+  /**<br>
+  * @defgroup FlipFlop Flip-Flop<br>
+  *<br>
+  * @brief Simple Flip-Flop state machine.<br>
+  *<br>
+  * @dot<br>
+  *   digraph {<br>
+  *     start [label="START"];<br>
+  *     flip [label="FLIP"];<br>
+  *     flop [label="FLOP"];<br>
+  *     flip -> flop [label="flop()", URL="\ref flop"];<br>
+  *     flop -> flip [label="flip()", URL="\ref flip"];<br>
+  *     start -> flip<br>
+  *       [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];<br>
+  *     start -> flop<br>
+  *       [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];<br>
+  *     flip -> start<br>
+  *       [label="flip_flop_restart()", URL="\ref flip_flop_restart"];<br>
+  *   }<br>
+  * @enddot<br>
+  *<br>
+  * @{<br>
+  */<br>
+<br>
+enum and struct<br>
+---------------<br>
+<br>
+Provide documentation for declarations of enumerated types and structs.<br>
+Use typedefs for structs, and do not use ``_t`` as a typename suffix.<br>
+<br>
+.. code-block:: c<br>
+<br>
+  /**<br>
+  * @brief The set of possible flip-flop states.<br>
+  *<br>
+  * Enumerated type to define the set of states for a flip-flop.<br>
+  */<br>
+  typedef enum {<br>
+    START = 0,<br>
+    FLIP,<br>
+    FLOP<br>
+  } flip_flop_state;<br>
+<br>
+  /**<br>
+  * @brief Object containing multiple flip-flops.<br>
+  *<br>
+  * Encapsulates multiple flip-flops.<br>
+  */<br>
+  typedef struct {<br>
+    /**<br>
+    * @brief Primary flip-flop.<br>
+    */<br>
+    flip_flop_state primary;<br>
+    /**<br>
+    * @brief Secondary flip-flop.<br>
+    */<br>
+    flip_flop_state secondary;<br>
+  } flip_flop_multiple;<br>
+<br>
+Using @name for organization<br>
+----------------------------<br>
+<br>
+Complicated groups can be given additional organization by using ``@name``, or<br>
+by declaring additional groups within the hierarchy of the header file's<br>
+top-level group.<br>
+<br>
+.. code-block:: c<br>
+<br>
+  /**<br>
+  * @name Flip-Flop Maintenance<br>
+  *<br>
+  * @{<br>
+  */<br>
+<br>
+Declaring functions<br>
+-------------------<br>
+<br>
+Function declarations should have an @brief that states what the function does<br>
+in a single topic sentence starting with a descriptive verb in the present<br>
+tense.<br>
+<br>
+.. code-block:: c<br>
+<br>
+  /**<br>
+  * @brief Initializes the flip-flop state.<br>
+  *<br>
+  * @param[in] state The initial state to set the flip-flop.<br>
+  *<br>
+  * @retval RTEMS_SUCCESSFUL Successfully initialized.<br>
+  * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid.<br>
+  */<br>
+  rtems_status_code flip_flop_initialize(flip_flop_state state);<br>
+<br>
+  /**<br>
+  * @brief Restarts the flip-flop.<br>
+  *<br>
+  * @retval RTEMS_SUCCESSFUL Successfully restarted.<br>
+  * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.<br>
+  */<br>
+  rtems_status_code flip_flop_restart(void);<br>
+<br>
+Do not document trivial functions, such as getter/setter methods.<br>
+<br>
+.. code-block:: c<br>
+<br>
+  flip_flop_state flip_flop_current_state(void);<br>
+<br>
+Close the documentation name definition and open a new name definition. <br>
+<br>
+.. code-block:: c<br>
+<br>
+  /** @} */<br>
+<br>
+  /**<br>
+  * @name Flip-Flop Usage<br>
+  *<br>
+  * @{<br>
+  */<br>
+<br>
+  /**<br>
+  * @brief Flip operation.<br>
+  *<br>
+  * @retval RTEMS_SUCCESSFUL Flipped successfully.<br>
+  * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.<br>
+  */<br>
+  rtems_status_code flip( void );<br>
+<br>
+  /**<br>
+  * @brief Flop operation.<br>
+  *<br>
+  * @retval RTEMS_SUCCESSFUL Flopped successfully.<br>
+  * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.<br>
+  */<br>
+  rtems_status_code flop( void );<br>
+<br>
+  /** @} */<br>
+<br>
+Ending the file<br>
+---------------<br>
+<br>
+Close the documentation group definition, then the extern C declarations,<br>
+then the header guard.<br>
+<br>
+.. code-block:: c<br>
+<br>
+  /** @} */<br>
+<br>
+  #ifdef __cplusplus<br>
+  }<br>
+  #endif /* __cplusplus */<br>
+<br>
+  #endif /* RTEMS_LIB_FLIP_FLOP_H */<br>
+<br>
+ No newline at the end of the file.<br>
+<br>
+Source File Example<br>
+-------------------<br>
+<br>
+.. code-block:: c<br>
+<br>
+  /**<br>
+  * @file<br>
+  *<br>
+  * @ingroup FlipFlop<br>
+  *<br>
+  * @brief Flip-Flop implementation.<br>
+  */<br>
+<br>
+  /*<br>
+  * Copyright (c) YYYY Author.<br>
+  *<br>
+  * The license and distribution terms for this file may be<br>
+  * found in the file LICENSE in this distribution or at<br>
+  * <a href="http://www.rtems.com/license/LICENSE" rel="noreferrer" target="_blank">http://www.rtems.com/license/LICENSE</a>.<br>
+  */<br>
+<br>
+  #include <rtems/lib/flipflop.h><br>
+<br>
+  static flip_flop_state current_state;<br>
+<br>
+  rtems_status_code flip_flop_initialize(flip_flop_state state)<br>
+  {<br>
+    if (current_state == START) {<br>
+      current_state = state;<br>
+<br>
+      return RTEMS_SUCCESSFUL;<br>
+    } else {<br>
+      return RTEMS_INCORRECT_STATE;<br>
+    }<br>
+  }<br>
+<br>
+  rtems_status_code flip_flop_restart(void)<br>
+  {<br>
+    if (current_state == FLIP) {<br>
+      current_state = START;<br>
+<br>
+      return RTEMS_SUCCESSFUL;<br>
+    } else {<br>
+      return RTEMS_INCORRECT_STATE;<br>
+    }<br>
+  }<br>
+<br>
+  flip_flop_state flip_flop_current_state(void)<br>
+  {<br>
+    return current_state;<br>
+  }<br>
+<br>
+  rtems_status_code flip(void)<br>
+  {<br>
+    if (current_state == FLOP) {<br>
+      current_state = FLIP;<br>
+<br>
+      return RTEMS_SUCCESSFUL;<br>
+    } else {<br>
+      return RTEMS_INCORRECT_STATE;<br>
+    }<br>
+  }<br>
+<br>
+  rtems_status_code flop(void)<br>
+  {<br>
+    if (current_state == FLIP) {<br>
+      current_state = FLOP;<br>
+<br>
+      return RTEMS_SUCCESSFUL;<br>
+    } else {<br>
+      return RTEMS_INCORRECT_STATE;<br>
+    }<br>
+  }<br>
+<br>
+Files<br>
+-----<br>
+Document files with the ``@file`` directive omitting the optional filename<br>
+argument. Doxygen will infer the filename from the actual name of the file.<br>
+Within one Doxygen run all files are unique and specified by the current<br>
+Doxyfile. We can define how the generated output of path and filenames looks<br>
+like in the Doxyfile via the ``FULL_PATH_NAMES``, ``STRIP_FROM_PATH`` and<br>
+``STRIP_FROM_INC_PATH`` options.<br>
+<br>
+Functions<br>
+---------<br>
+<br>
+For documentation of function arguments there are basically to ways:<br>
+<br>
+The first one uses ``@param``:<br>
+<br>
+.. code-block:: c<br>
+  <br>
+  /**<br>
+  * @brief Copies from a source to a destination memory area.<br>
+  *<br>
+  * The source and destination areas may not overlap.<br>
+  * <br>
+  * @param[out] dest The destination memory area to copy to.<br>
+  * @param[in] src The source memory area to copy from.<br>
+  * @param[in] n The number of bytes to copy.<br>
+  */<br>
+<br>
+The second is to use ``@a`` param in descriptive text, for example:<br>
+<br>
+.. code-block:: c<br>
+  <br>
+  /**<br>
+  * Copies @a n bytes from a source memory area @a src to a destination memory<br>
+  * area @a dest, where both areas may not overlap.<br>
+  */<br>
+<br>
+The ``@a`` indicates that the next word is a function argument and deserves<br>
+some kind of highlighting. However, we feel that ``@a`` buries the usage of<br>
+function arguments within description text. In RTEMS sources, we prefer to<br>
+use ``@param`` instead of ``@a``. <br>
+<br>
+.. COMMENT: TBD - Add Doxyfile Hints<br>
+<br>
+Header Files<br>
+------------<br>
+<br>
+It is an RTEMS build feature that header files need to be installed in order to<br>
+be useful. One workaround to generate documentation which allows automatic<br>
+link generation is to use the installed header files as documentation input.<br>
+Assume that we have the RTEMS sources in the rtems directory and the build of<br>
+our BSP in build/powerpc-rtems5/mybsp relative to a common top-level directory.<br>
+Then you can configure Doxygen like:<br>
+<br>
+.. code-block::<br>
+<br>
+  INPUT           = rtems/bsps/powerpc/mybsp \<br>
+                    rtems/c/src/lib/libcpu/powerpc/mycpu \<br>
+                    rtems/make/custom/mybsp.cfg \<br>
+                    build/powerpc-rtems5/mybsp/lib/include/myincludes<br>
+<br>
+  RECURSIVE       = YES<br>
+<br>
+  EXCLUDE         = rtems/bsps/powerpc/mybsp/include \<br>
+                    rtems/c/src/lib/libcpu/powerpc/mycpu/include<br>
+<br>
+  FULL_PATH_NAMES = YES<br>
+<br>
+  STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \<br>
+                    rtems<br>
+<br>
+Script and Assembly Files<br>
+-------------------------<br>
+<br>
+Doxygen cannot cope with script (= files with #-like comments) or assembly files.<br>
+But you can add filter programs for them<br>
+<br>
+.. COMMENT: TBD - Add source code for filter programs somewhere<br>
+<br>
+.. code-block::<br>
+<br>
+  FILTER_PATTERNS = *.S=c-comments-only \<br>
+                    *.s=c-comments-only \<br>
+                    *.cfg=script-comments-only \<br>
+                    *.am=script-comments-only \<br>
+                    *.ac=script-comments-only<br>
+<br>
+Assembly Example<br>
+~~~~~~~~~~~~~~~~<br>
+<br>
+.. code-block:: c<br>
+<br>
+  /**<br>
+  * @fn void mpc55xx_fmpll_reset_config()<br>
+  *<br>
+  * @brief Configure FMPLL after reset.<br>
+  *<br>
+  * Sets the system clock from 12 MHz in two steps up to 128 MHz.<br>
+  */<br>
+  GLOBAL_FUNCTION mpc55xx_fmpll_reset_config<br>
+      /* Save link register */<br>
+      mflr r3<br>
+<br>
+      LA r4, FMPLL_SYNCR<br>
+<br>
+You have to put a declaration of this function somewhere in a header file.<br>
+<br>
+Script Example<br>
+~~~~~~~~~~~~~~<br>
+<br>
+.. code-block:: python<br>
+<br>
+  ##<br>
+  #<br>
+  # @file<br>
+  #<br>
+  # @ingroup mpc55xx_config<br>
+  #<br>
+  # @brief Configure script of LibBSP for the MPC55xx evaluation boards.<br>
+  #<br>
+<br>
+  AC_PREREQ([2.69])<br>
+  AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[<a href="https://devel.rtems.org/newticket" rel="noreferrer" target="_blank">https://devel.rtems.org/newticket</a>])<br>
+<br>
+<br>
+GCC Attributes<br>
+--------------<br>
+<br>
+The Doxygen C/C++ parser cannot cope with the GCC ``attribute((something))`` stuff.<br>
+But you can discard such features with pre-defined preprocessor macros<br>
+<br>
+.. code-block:: none<br>
+<br>
+  ENABLE_PREPROCESSING = YES<br>
+  MACRO_EXPANSION      = YES<br>
+  EXPAND_ONLY_PREDEF   = YES<br>
+  PREDEFINED           = __attribute__(x)=<br>
+<br>
+History<br>
+-------<br>
+<br>
+RTEMS is much older than `Doxygen <<a href="http://www.doxygen.org/" rel="noreferrer" target="_blank">http://www.doxygen.org/</a>>`_ and the<br>
+documentation in the .h and .inl files was obviously not written with<br>
+`Doxygen markup <<a href="http://www.stack.nl/~dimitri/doxygen/manual.html" rel="noreferrer" target="_blank">http://www.stack.nl/~dimitri/doxygen/manual.html</a>>`_. In<br>
+2007, Joel Sherrill undertook to convert the documentation in the .h and .inl<br>
+files in the RTEMS SuperCore to Doxygen format. As a result of this effort,<br>
+the Doxygen for the development version of the RTEMS SuperCore is now built automatically<br>
+multiple times per day and made available on the RTEMS Website. In April 2008,<br>
+Joel Sherrill began to update the Classic API (e.g. cpukit/rtems) .h and .inl<br>
+files to include Doxygen markup.<br>
+<br>
diff --git a/eng/coding-file-hdr.rst b/eng/coding-file-hdr.rst<br>
index 1ff16b8..f273e03 100644<br>
--- a/eng/coding-file-hdr.rst<br>
+++ b/eng/coding-file-hdr.rst<br>
@@ -7,6 +7,7 @@<br>
 .. COMMENT:TBD  - Convert the following to Rest and insert into this file<br>
 .. COMMENT:TBD - <a href="https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header" rel="noreferrer" target="_blank">https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header</a><br>
<br>
+.. _coding-file-hdr:<br>
<br>
 Boilerplate File Header<br>
 =======================<br>
-- <br>
2.17.1<br>
<br>
</blockquote></div>