[PATCH] eng/coding-doxygen: Convert wiki page to Rest
Joel Sherrill
joel at rtems.org
Tue Dec 4 21:18:17 UTC 2018
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 <mcomajoancara at 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 <joel at 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 <
>> mcomajoancara at 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
>>>
>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20181204/28ffbc48/attachment-0002.html>
More information about the devel
mailing list