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