Sure! On Tue, Dec 4, 2018 at 10:18 PM Joel Sherrill <j...@rtems.org> wrote:
> 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
