Changeset cd6ac10 in rtems-docs


Ignore:
Timestamp:
Dec 3, 2018, 9:40:15 AM (5 months ago)
Author:
zehata <zenon.hans.taneka@…>
Branches:
master
Children:
f5c20a6
Parents:
edde29e
git-author:
zehata <zenon.hans.taneka@…> (12/03/18 09:40:15)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:45:50)
Message:

Converted Doxygen Best Practices Documentation to Rest format (GCI 2018)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • eng/coding-doxygen.rst

    redde29e rcd6ac10  
    55
    66General Doxygen Recommentations
    7 ===============================
     7-------------------------------
    88
    99TBD - Convert the following to Rest and insert into this file
    1010TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
     11
     12Doxygen Best Practices
     13----------------------
     14
     15* Do not use @a. Instead use @param to document function parameters.
     16* Do not use @return. Instead use @retval to document return status codes.
     17* Do not write documentation for trivial functions.
     18* Do not repeat documentation, use @see for example.
     19* Do not use @note.
     20* Use groups and arrange them in a hierarchy. Put every file into at least one group.
     21* Use dot comments for state diagrams.
     22* Use one whitespace character after an asterisk.
     23
     24Special Notes for Google Code In Students
     25-----------------------------------------
     26
     27* 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.
     28
     29Header File Example
     30-------------------
     31
     32​`thread.h <https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/thread.h>`_ and `​threadimpl.h <https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/threadimpl.h>`_ should be a good example of how a header file should be written. The following gives details in bits and pieces.
     33
     34Header blocks
     35-------------
     36
     37Header files should contain the similar comment blocks as other source files, described at `Boilerplate File Header <https://devel.rtems.org/wiki/Developer/Coding/Boilerplate_File_Header>`_.
     38
     39        .. code-block:: c
     40
     41                /**
     42                 * @file
     43                 *
     44                 * @ingroup FlipFlop
     45                 *
     46                 * @brief Flip-Flop API
     47                 */
     48
     49                /*
     50                 * Copyright (c) YYYY Author.
     51                 *
     52                 * The license and distribution terms for this file may be
     53                 * found in the file LICENSE in this distribution or at
     54                 * http://www.rtems.com/license/LICENSE.
     55                 */
     56
     57Header guard
     58------------
     59
     60After 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
     61
     62        .. code-block:: c
     63
     64                #ifndef RTEMS_LIB_FLIP_FLOP_H
     65                #define RTEMS_LIB_FLIP_FLOP_H
     66
     67Includes
     68--------
     69
     70Then add your include files before protecting C declarations from C++.
     71
     72
     73        .. code-block:: c
     74
     75                #include <rtems.h>
     76
     77                #ifdef __cplusplus
     78                extern "C" {
     79                #endif /* __cplusplus */
     80
     81Using @defgroup for group definitions
     82-------------------------------------
     83
     84Add 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.
     85
     86
     87        .. code-block:: c
     88
     89                /**
     90                 * @defgroup FlipFlop Flip-Flop
     91                 *
     92                 * @brief Simple Flip-Flop state machine.
     93                 *
     94                 * @dot
     95                 *   digraph {
     96                 *     start [label="START"];
     97                 *     flip [label="FLIP"];
     98                 *     flop [label="FLOP"];
     99                 *     flip -> flop [label="flop()", URL="\ref flop"];
     100                 *     flop -> flip [label="flip()", URL="\ref flip"];
     101                 *     start -> flip
     102                 *       [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];
     103                 *     start -> flop
     104                 *       [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];
     105                 *     flip -> start
     106                 *       [label="flip_flop_restart()", URL="\ref flip_flop_restart"];
     107                 *   }
     108                 * @enddot
     109                 *
     110                 * @{
     111                 */
     112
     113enum and struct
     114---------------
     115
     116Provide documentation for declarations of enumerated types and structs. Use typedefs for structs, and do not use _t as a typename suffix.
     117
     118
     119        .. code-block:: c
     120
     121                /**
     122                 * @brief The set of possible flip-flop states.
     123                 *
     124                 * Enumerated type to define the set of states for a flip-flop.
     125                 */
     126                typedef enum {
     127                  START = 0,
     128                  FLIP,
     129                  FLOP
     130                } flip_flop_state;
     131
     132                /**
     133                 * @brief Object containing multiple flip-flops.
     134                 *
     135                 * Encapsulates multiple flip-flops.
     136                 */
     137                typedef struct {
     138                  /**
     139                   * @brief Primary flip-flop.
     140                   */
     141                  flip_flop_state primary;
     142                  /**
     143                   * @brief Secondary flip-flop.
     144                   */
     145                  flip_flop_state secondary;
     146                } flip_flop_multiple;
     147
     148
     149Using @name for organization
     150----------------------------
     151
     152Complicated 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.
     153
     154        .. code-block:: c
     155
     156                /**
     157                 * @name Flip-Flop Maintenance
     158                 *
     159                 * @{
     160                 */
     161
     162Declaring functions
     163-------------------
     164
     165Function 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.
     166
     167
     168        .. code-block:: c
     169                /**
     170                 * @brief Initializes the flip-flop state.
     171                 *
     172                 * @param[in] state The initial state to set the flip-flop.
     173                 *
     174                 * @retval RTEMS_SUCCESSFUL Successfully initialized.
     175                 * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid.
     176                 */
     177                rtems_status_code flip_flop_initialize(flip_flop_state state);
     178
     179                /**
     180                 * @brief Restarts the flip-flop.
     181                 *
     182                 * @retval RTEMS_SUCCESSFUL Successfully restarted.
     183                 * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
     184                 */
     185                rtems_status_code flip_flop_restart(void);
     186
     187Do not document trivial functions, such as getter/setter methods.
     188
     189        .. code-block:: c
     190                flip_flop_state flip_flop_current_state(void);
     191
     192Close the documentation name definition and open a new name definition.
     193
     194        .. code-block:: c
     195                /** @} */
     196
     197                /**
     198                 * @name Flip-Flop Usage
     199                 *
     200                 * @{
     201                 */
     202
     203                /**
     204                 * @brief Flip operation.
     205                 *
     206                 * @retval RTEMS_SUCCESSFUL Flipped successfully.
     207                 * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
     208                 */
     209                rtems_status_code flip( void );
     210
     211                /**
     212                 * @brief Flop operation.
     213                 *
     214                 * @retval RTEMS_SUCCESSFUL Flopped successfully.
     215                 * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
     216                 */
     217                rtems_status_code flop( void );
     218
     219                /** @} */
     220
     221Ending the file
     222---------------
     223
     224Close the documentation group definition, then the extern C declarations, then the header guard.
     225
     226        .. code-block:: c
     227                /** @} */
     228
     229                #ifdef __cplusplus
     230                }
     231                #endif /* __cplusplus */
     232
     233                #endif /* RTEMS_LIB_FLIP_FLOP_H */
     234
     235No newline at the end of the file.
     236
     237Source File Example
     238-------------------
     239
     240        .. code-block:: c
     241
     242                /**
     243                 * @file
     244                 *
     245                 * @ingroup FlipFlop
     246                 *
     247                 * @brief Flip-Flop implementation.
     248                 */
     249
     250                /*
     251                 * Copyright (c) YYYY Author.
     252                 *
     253                 * The license and distribution terms for this file may be
     254                 * found in the file LICENSE in this distribution or at
     255                 * http://www.rtems.com/license/LICENSE.
     256                 */
     257
     258                #include <rtems/lib/flipflop.h>
     259
     260                static flip_flop_state current_state;
     261
     262                rtems_status_code flip_flop_initialize(flip_flop_state state)
     263                {
     264                  if (current_state == START) {
     265                    current_state = state;
     266
     267                    return RTEMS_SUCCESSFUL;
     268                  } else {
     269                    return RTEMS_INCORRECT_STATE;
     270                  }
     271                }
     272
     273                rtems_status_code flip_flop_restart(void)
     274                {
     275                  if (current_state == FLIP) {
     276                    current_state = START;
     277
     278                    return RTEMS_SUCCESSFUL;
     279                  } else {
     280                    return RTEMS_INCORRECT_STATE;
     281                  }
     282                }
     283
     284                flip_flop_state flip_flop_current_state(void)
     285                {
     286                  return current_state;
     287                }
     288
     289                rtems_status_code flip(void)
     290                {
     291                  if (current_state == FLOP) {
     292                    current_state = FLIP;
     293
     294                    return RTEMS_SUCCESSFUL;
     295                  } else {
     296                    return RTEMS_INCORRECT_STATE;
     297                  }
     298                }
     299
     300                rtems_status_code flop(void)
     301                {
     302                  if (current_state == FLIP) {
     303                    current_state = FLOP;
     304
     305                    return RTEMS_SUCCESSFUL;
     306                  } else {
     307                    return RTEMS_INCORRECT_STATE;
     308                  }
     309                }
     310
     311Files
     312-----
     313
     314Document 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.
     315
     316Functions
     317---------
     318
     319For documentation of function arguments there are basically to ways: The first one uses @param:
     320
     321        .. code-block::
     322                /**
     323                 * @brief Copies from a source to a destination memory area.
     324                 *
     325                 * The source and destination areas may not overlap.
     326                 *
     327                 * @param[out] dest The destination memory area to copy to.
     328                 * @param[in] src The source memory area to copy from.
     329                 * @param[in] n The number of bytes to copy.
     330                 */
     331                The second is to use @a param in descriptive text, for example:
     332
     333                /**
     334                 * Copies @a n bytes from a source memory area @a src to a destination memory
     335                 * area @a dest, where both areas may not overlap.
     336                 */
     337
     338The @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.
     339
     340Doxyfile Hints
     341--------------
     342
     343Header Files
     344------------
     345
     346It 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:
     347
     348
     349        .. code-block::
     350                INPUT           = rtems/bsps/powerpc/mybsp \
     351                                  rtems/c/src/lib/libcpu/powerpc/mycpu \
     352                                  rtems/make/custom/mybsp.cfg \
     353                                  build/powerpc-rtems5/mybsp/lib/include/myincludes
     354
     355                RECURSIVE       = YES
     356
     357                EXCLUDE         = rtems/bsps/powerpc/mybsp/include \
     358                                  rtems/c/src/lib/libcpu/powerpc/mycpu/include
     359
     360                FULL_PATH_NAMES = YES
     361
     362                STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \
     363                                  rtems
     364
     365Script and Assembly Files
     366-------------------------
     367
     368Doxygen cannot cope with script (= files with #-like comments) or assembly files. But you can add filter programs for them (TODO: Add source code for filter programs somewhere):
     369
     370        .. code-block::
     371                FILTER_PATTERNS = *.S=c-comments-only \
     372                                  *.s=c-comments-only \
     373                                  *.cfg=script-comments-only \
     374                                  *.am=script-comments-only \
     375                                  *.ac=script-comments-only
     376
     377Assembly Example
     378----------------
     379
     380        .. code-block::
     381                /**
     382                 * @fn void mpc55xx_fmpll_reset_config()
     383                 *
     384                 * @brief Configure FMPLL after reset.
     385                 *
     386                 * Sets the system clock from 12 MHz in two steps up to 128 MHz.
     387                 */
     388                GLOBAL_FUNCTION mpc55xx_fmpll_reset_config
     389                    /* Save link register */
     390                    mflr r3
     391
     392                    LA r4, FMPLL_SYNCR
     393
     394You have to put a declaration of this function somewhere in a header file.
     395
     396Script Example
     397--------------
     398
     399        .. code-block::
     400                ##
     401                #
     402                # @file
     403                #
     404                # @ingroup mpc55xx_config
     405                #
     406                # @brief Configure script of LibBSP for the MPC55xx evaluation boards.
     407                #
     408
     409                AC_PREREQ(2.60)
     410                AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla])
     411
     412GCC Attributes
     413--------------
     414
     415The Doxygen C/C++ parser cannot cope with the GCC attribute((something)) stuff. But you can discard such features with pre-defined preprocessor macros:
     416
     417        .. code-block::
     418                ENABLE_PREPROCESSING = YES
     419                MACRO_EXPANSION      = YES
     420                EXPAND_ONLY_PREDEF   = YES
     421                PREDEFINED           = __attribute__(x)=
     422
     423History
     424-------
     425
     426RTEMS 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, `JoelSherrill <https://devel.rtems.org/wiki/TBR/User/JoelSherrill>`_ 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 RTEMSSuperCore is now built automatically multiple times per day and made available on the RTEMS Website. In April 2008, `JoelSherrill <https://devel.rtems.org/wiki/TBR/User/JoelSherrill>`_ began to update the Classic API (e.g. cpukit/rtems) .h and .inl files to include `​Doxygen markup <http://www.stack.nl/~dimitri/doxygen/manual.html>`_.
Note: See TracChangeset for help on using the changeset viewer.