<div dir="ltr"><div dir="ltr"><div>How about a new task to fix them and submit a patch? :)<br></div><div><br></div><div><a href="https://codein.withgoogle.com/dashboard/tasks/6126294447161344/">https://codein.withgoogle.com/dashboard/tasks/6126294447161344/</a></div><div><br></div><div>--joel<br></div></div></div><br><div class="gmail_quote"><div dir="ltr">On Tue, Dec 4, 2018 at 2:01 PM Marçal <<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"><div dir="ltr"><div dir="ltr">Hi, it's weird because the task to do the 
eng/coding-doxygen was claimed but me but apparently another student did
 the conversion before.</div><div dir="ltr">However, I see some things 
wrong that I think were correct in my conversion, for example, the TBDs 
are not turned into comments, the links on Header File Example point to 
the old locations (so it shows a not found error) and should link to the
 new ones that you told me, the link to Boilerplate File Header could be changed to link 
the Handbook section instead of the wiki, and also some things are not 
correctly formatted so they are displayed wrong. Looking at the code I also see that some lines are 
longer than 80 characters. In my conversion I also had formatted some 
Doxygen keywords to look nicer and more understandable and changed the 
Script Example with a newer version showing a link 
<a href="https://devel.rtems.org/newticket" target="_blank">https://devel.rtems.org/newticket</a> instead of 
<a href="http://www.rtems.org/bugzilla" target="_blank">http://www.rtems.org/bugzilla</a> which might generate confusion because 
it's the old system.</div><div>I think it would be nice to fix the above things. What should I do to help with it?</div><div><br></div><div>Marçal<br></div></div><br><div class="gmail_quote"><div dir="ltr">On Tue, Dec 4, 2018 at 8:34 PM Joel Sherrill <<a href="mailto:joel@rtems.org" target="_blank">joel@rtems.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><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" target="_blank">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>
</blockquote></div>
</blockquote></div>