Changeset cc826d7 in rtems-docs


Ignore:
Timestamp:
Dec 5, 2018, 2:43:00 PM (5 months ago)
Author:
Marçal Comajoan Cara <mcomajoancara@…>
Branches:
master
Children:
75f2463
Parents:
b8b4f14
git-author:
Marçal Comajoan Cara <mcomajoancara@…> (12/05/18 14:43:00)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:45:50)
Message:

eng/coding-doxygen: Fix errors

This work was part of GCI 2018.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • eng/coding-doxygen.rst

    rb8b4f14 rcc826d7  
    55
    66General Doxygen Recommentations
    7 -------------------------------
    8 
    9 TBD - Convert the following to Rest and insert into this file
    10 TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
     7===============================
     8
     9.. COMMENT: TBD - Convert the following to Rest and insert into this file
     10.. COMMENT: TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
    1111
    1212.. sidebar:: *History*
     
    2424
    2525Doxygen Best Practices
    26 ^^^^^^^^^^^^^^^^^^^^^^
    27 
    28 * Do not use @a. Instead use @param to document function parameters.
    29 * Do not use @return. Instead use @retval to document return status codes.
     26----------------------
     27
     28* Do not use ``@a``. Instead use ``@param`` to document function parameters.
     29* Do not use ``@return``. Instead use ``@retval`` to document return status
     30  codes.
    3031* Do not write documentation for trivial functions.
    31 * Do not repeat documentation, use @see for example.
    32 * Do not use @note.
    33 * Use groups and arrange them in a hierarchy. Put every file into at least one group.
     32* Do not repeat documentation, use ``@see`` for example.
     33* Do not use ``@note``.
     34* Use groups and arrange them in a hierarchy. Put every file into at least
     35  one group.
    3436* Use dot comments for state diagrams.
    3537* Use one whitespace character after an asterisk.
    3638
    37 Special Notes for Google Code In Students
    38 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    39 
    40 * Follow the directions given by the `Google Code In
    41 <https://devel.rtems.org/wiki/GCI>`_ task and this should take care
    42 of itself if in doubt ask a mentor and/or tell a mentor the decision
    43 you made.
     39Special Notes for Google Code-in Students
     40-----------------------------------------
     41
     42Follow the directions given by the `Google Code-in
     43<https://devel.rtems.org/wiki/GCI>`_ task and this should take
     44care of itself if in doubt ask a mentor and/or tell a mentor the decision you
     45made.
    4446
    4547Header File Example
    46 ^^^^^^^^^^^^^^^^^^^
    47 
    48 The files *thread.h*
    49 (https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/thread.h)
    50 and *threadimpl.h*
    51 (https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/threadimpl.h)
    52 should be a good example of how a header file should be written. The
    53 following gives details in bits and pieces.
     48-------------------
     49
     50`thread.h
     51<https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/thread.h>`_ and
     52`threadimpl.h
     53<https://git.rtems.org/rtems/tree/cpukit/include/rtems/score/threadimpl.h>`_
     54should be a good example of how a header file shouldbe written. The following
     55gives details in bits and pieces.
    5456
    5557Header blocks
    56 ^^^^^^^^^^^^^
    57 
    58 Header 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>`_.
    59 
    60     .. code-block:: c
    61 
    62         /**
    63          * @file
    64          *
    65          * @ingroup FlipFlop
    66          *
    67          * @brief Flip-Flop API
    68          */
    69 
    70         /*
    71          * Copyright (c) YYYY Author.
    72          *
    73          * The license and distribution terms for this file may be
    74          * found in the file LICENSE in this distribution or at
    75          * http://www.rtems.com/license/LICENSE.
    76          */
    77 
    78 Header Guard
    79 ^^^^^^^^^^^^
    80 
    81 After the comment blocks, use a header guard that assembles at
    82 least the include path of the file. For example, if flipflop.h is in
    83 <rtems/lib/flipflop.h> then
    84 
    85     .. code-block:: c
    86 
    87         #ifndef RTEMS_LIB_FLIP_FLOP_H
    88         #define RTEMS_LIB_FLIP_FLOP_H
     58-------------
     59
     60Header files should contain the similar comment blocks as other source files,
     61described at :ref:`coding-file-hdr`.
     62
     63.. code-block:: c
     64
     65  /**
     66   * @file
     67   *
     68   * @ingroup FlipFlop
     69   *
     70   * @brief Flip-Flop API
     71   */
     72
     73  /*
     74   * Copyright (c) YYYY Author.
     75   *
     76   * The license and distribution terms for this file may be
     77   * found in the file LICENSE in this distribution or at
     78   * http://www.rtems.com/license/LICENSE.
     79   */
     80
     81Header guard
     82------------
     83
     84After the comment blocks, use a header guard that assembles at least the
     85include path of the file. For example, if ``flipflop.h`` is in
     86``<rtems/lib/flipflop.h>`` then
     87
     88.. code-block:: c
     89
     90  #ifndef RTEMS_LIB_FLIP_FLOP_H
     91  #define RTEMS_LIB_FLIP_FLOP_H
    8992
    9093Includes
    91 ^^^^^^^^
     94--------
    9295
    9396Then add your include files before protecting C declarations from C++.
    9497
    95 
    96     .. code-block:: c
    97 
    98         #include <rtems.h>
    99 
    100         #ifdef __cplusplus
    101         extern "C" {
    102         #endif /* __cplusplus */
     98.. code-block:: c
     99
     100  #include <rtems.h>
     101
     102  #ifdef __cplusplus
     103  extern "C" {
     104  #endif /* __cplusplus */
    103105
    104106Using @defgroup for group definitions
    105 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    106 
    107 Add any group definitions surrounding the function declarations
    108 that belong in that group. Rarely, a header may define more than one
    109 group. Here we use a dot diagram.
    110 
    111 
    112     .. code-block:: c
    113 
    114         /**
    115          * @defgroup FlipFlop Flip-Flop
    116          *
    117          * @brief Simple Flip-Flop state machine.
    118          *
    119          * @dot
    120          *   digraph {
    121          *     start [label="START"];
    122          *     flip [label="FLIP"];
    123          *     flop [label="FLOP"];
    124          *     flip -> flop [label="flop()", URL="\ref flop"];
    125          *     flop -> flip [label="flip()", URL="\ref flip"];
    126          *     start -> flip
    127          *       [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];
    128          *     start -> flop
    129          *       [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];
    130          *     flip -> start
    131          *       [label="flip_flop_restart()", URL="\ref flip_flop_restart"];
    132          *   }
    133          * @enddot
    134          *
    135          * @{
    136          */
     107-------------------------------------
     108
     109Add any group definitions surrounding the function declarations that belong
     110in that group. Rarely, a header may define more than one group. Here we use
     111a dot diagram.
     112
     113.. code-block:: c
     114
     115  /**
     116   * @defgroup FlipFlop Flip-Flop
     117   *
     118   * @brief Simple Flip-Flop state machine.
     119   *
     120   * @dot
     121   *   digraph {
     122   *     start [label="START"];
     123   *     flip [label="FLIP"];
     124   *     flop [label="FLOP"];
     125   *     flip -> flop [label="flop()", URL="\ref flop"];
     126   *     flop -> flip [label="flip()", URL="\ref flip"];
     127   *     start -> flip
     128   *       [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"];
     129   *     start -> flop
     130   *       [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"];
     131   *     flip -> start
     132   *       [label="flip_flop_restart()", URL="\ref flip_flop_restart"];
     133   *   }
     134   * @enddot
     135   *
     136   * @{
     137   */
    137138
    138139enum and struct
    139 ^^^^^^^^^^^^^^^
    140 
    141 Provide documentation for declarations of enumerated types and
    142 structs. Use typedefs for structs, and do not use _t as a typename suffix.
    143 
    144 
    145     .. code-block:: c
    146 
    147         /**
    148          * @brief The set of possible flip-flop states.
    149          *
    150          * Enumerated type to define the set of states for a flip-flop.
    151          */
    152         typedef enum {
    153           START = 0,
    154           FLIP,
    155           FLOP
    156         } flip_flop_state;
    157 
    158         /**
    159          * @brief Object containing multiple flip-flops.
    160          *
    161          * Encapsulates multiple flip-flops.
    162          */
    163         typedef struct {
    164           /**
    165            * @brief Primary flip-flop.
    166            */
    167           flip_flop_state primary;
    168           /**
    169            * @brief Secondary flip-flop.
    170            */
    171           flip_flop_state secondary;
    172         } flip_flop_multiple;
    173 
     140---------------
     141
     142Provide documentation for declarations of enumerated types and structs.
     143Use typedefs for structs, and do not use ``_t`` as a typename suffix.
     144
     145.. code-block:: c
     146
     147  /**
     148   * @brief The set of possible flip-flop states.
     149   *
     150   * Enumerated type to define the set of states for a flip-flop.
     151   */
     152  typedef enum {
     153    START = 0,
     154    FLIP,
     155    FLOP
     156  } flip_flop_state;
     157
     158  /**
     159   * @brief Object containing multiple flip-flops.
     160   *
     161   * Encapsulates multiple flip-flops.
     162   */
     163  typedef struct {
     164    /**
     165     * @brief Primary flip-flop.
     166     */
     167    flip_flop_state primary;
     168    /**
     169     * @brief Secondary flip-flop.
     170     */
     171    flip_flop_state secondary;
     172  } flip_flop_multiple;
    174173
    175174Using @name for organization
    176 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    177 
    178 Complicated groups can be given additional organization by using @name,
    179 or by declaring additional groups within the hierarchy of the header
    180 file's top-level group.
    181 
    182     .. code-block:: c
    183 
    184         /**
    185          * @name Flip-Flop Maintenance
    186          *
    187          * @{
    188          */
     175----------------------------
     176
     177Complicated groups can be given additional organization by using ``@name``, or
     178by declaring additional groups within the hierarchy of the header file's
     179top-level group.
     180
     181.. code-block:: c
     182
     183  /**
     184   * @name Flip-Flop Maintenance
     185   *
     186   * @{
     187   */
    189188
    190189Declaring functions
    191 ^^^^^^^^^^^^^^^^^^^
    192 
    193 Function declarations should have an @brief that states what the function
    194 does in a single topic sentence starting with a descriptive verb in the
    195 present tense.
    196 
    197 
    198     .. code-block:: c
    199 
    200         /**
    201          * @brief Initializes the flip-flop state.
    202          *
    203          * @param[in] state The initial state to set the flip-flop.
    204          *
    205          * @retval RTEMS_SUCCESSFUL Successfully initialized.
    206          * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid.
    207          */
    208         rtems_status_code flip_flop_initialize(flip_flop_state state);
    209 
    210         /**
    211          * @brief Restarts the flip-flop.
    212          *
    213          * @retval RTEMS_SUCCESSFUL Successfully restarted.
    214          * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
    215          */
    216         rtems_status_code flip_flop_restart(void);
     190-------------------
     191
     192Function declarations should have an @brief that states what the function does
     193in a single topic sentence starting with a descriptive verb in the present
     194tense.
     195
     196.. code-block:: c
     197
     198  /**
     199   * @brief Initializes the flip-flop state.
     200   *
     201   * @param[in] state The initial state to set the flip-flop.
     202   *
     203   * @retval RTEMS_SUCCESSFUL Successfully initialized.
     204   * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid.
     205   */
     206  rtems_status_code flip_flop_initialize(flip_flop_state state);
     207
     208  /**
     209   * @brief Restarts the flip-flop.
     210   *
     211   * @retval RTEMS_SUCCESSFUL Successfully restarted.
     212   * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state.
     213   */
     214  rtems_status_code flip_flop_restart(void);
    217215
    218216Do not document trivial functions, such as getter/setter methods.
    219217
    220     .. code-block:: c
    221 
    222         flip_flop_state flip_flop_current_state(void);
     218.. code-block:: c
     219
     220  flip_flop_state flip_flop_current_state(void);
    223221
    224222Close the documentation name definition and open a new name definition.
    225223
    226     .. code-block:: c
    227 
    228         /** @} */
    229 
    230         /**
    231          * @name Flip-Flop Usage
    232          *
    233          * @{
    234          */
    235 
    236         /**
    237          * @brief Flip operation.
    238          *
    239          * @retval RTEMS_SUCCESSFUL Flipped successfully.
    240          * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
    241          */
    242         rtems_status_code flip( void );
    243 
    244         /**
    245          * @brief Flop operation.
    246          *
    247          * @retval RTEMS_SUCCESSFUL Flopped successfully.
    248          * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
    249          */
    250         rtems_status_code flop( void );
    251 
    252         /** @} */
     224.. code-block:: c
     225
     226  /** @} */
     227
     228  /**
     229   * @name Flip-Flop Usage
     230   *
     231   * @{
     232   */
     233
     234  /**
     235   * @brief Flip operation.
     236   *
     237   * @retval RTEMS_SUCCESSFUL Flipped successfully.
     238   * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
     239   */
     240  rtems_status_code flip( void );
     241
     242  /**
     243   * @brief Flop operation.
     244   *
     245   * @retval RTEMS_SUCCESSFUL Flopped successfully.
     246   * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
     247   */
     248  rtems_status_code flop( void );
     249
     250  /** @} */
    253251
    254252Ending the file
    255 ^^^^^^^^^^^^^^^
     253---------------
    256254
    257255Close the documentation group definition, then the extern C declarations,
    258256then the header guard.
    259257
    260     .. code-block:: c
    261 
    262         /** @} */
    263 
    264         #ifdef __cplusplus
    265         }
    266         #endif /* __cplusplus */
    267 
    268         #endif /* RTEMS_LIB_FLIP_FLOP_H */
    269 
    270 No newline at the end of the file.
     258.. code-block:: c
     259
     260  /** @} */
     261
     262  #ifdef __cplusplus
     263  }
     264  #endif /* __cplusplus */
     265
     266  #endif /* RTEMS_LIB_FLIP_FLOP_H */
     267
     268 No newline at the end of the file.
    271269
    272270Source File Example
    273 ^^^^^^^^^^^^^^^^^^^
    274 
    275     .. code-block:: c
    276 
    277         /**
    278          * @file
    279          *
    280          * @ingroup FlipFlop
    281          *
    282          * @brief Flip-Flop implementation.
    283          */
    284 
    285         /*
    286          * Copyright (c) YYYY Author.
    287          *
    288          * The license and distribution terms for this file may be
    289          * found in the file LICENSE in this distribution or at
    290          * http://www.rtems.com/license/LICENSE.
    291          */
    292 
    293         #include <rtems/lib/flipflop.h>
    294 
    295         static flip_flop_state current_state;
    296 
    297         rtems_status_code flip_flop_initialize(flip_flop_state state)
    298         {
    299           if (current_state == START) {
    300             current_state = state;
    301 
    302             return RTEMS_SUCCESSFUL;
    303           } else {
    304             return RTEMS_INCORRECT_STATE;
    305           }
    306         }
    307 
    308         rtems_status_code flip_flop_restart(void)
    309         {
    310           if (current_state == FLIP) {
    311             current_state = START;
    312 
    313             return RTEMS_SUCCESSFUL;
    314           } else {
    315             return RTEMS_INCORRECT_STATE;
    316           }
    317         }
    318 
    319         flip_flop_state flip_flop_current_state(void)
    320         {
    321           return current_state;
    322         }
    323 
    324         rtems_status_code flip(void)
    325         {
    326           if (current_state == FLOP) {
    327             current_state = FLIP;
    328 
    329             return RTEMS_SUCCESSFUL;
    330           } else {
    331             return RTEMS_INCORRECT_STATE;
    332           }
    333         }
    334 
    335         rtems_status_code flop(void)
    336         {
    337           if (current_state == FLIP) {
    338             current_state = FLOP;
    339 
    340             return RTEMS_SUCCESSFUL;
    341           } else {
    342             return RTEMS_INCORRECT_STATE;
    343           }
    344         }
     271-------------------
     272
     273.. code-block:: c
     274
     275  /**
     276   * @file
     277   *
     278   * @ingroup FlipFlop
     279   *
     280   * @brief Flip-Flop implementation.
     281   */
     282
     283  /*
     284   * Copyright (c) YYYY Author.
     285   *
     286   * The license and distribution terms for this file may be
     287   * found in the file LICENSE in this distribution or at
     288   * http://www.rtems.com/license/LICENSE.
     289   */
     290
     291  #include <rtems/lib/flipflop.h>
     292
     293  static flip_flop_state current_state;
     294
     295  rtems_status_code flip_flop_initialize(flip_flop_state state)
     296  {
     297    if (current_state == START) {
     298      current_state = state;
     299
     300      return RTEMS_SUCCESSFUL;
     301    } else {
     302      return RTEMS_INCORRECT_STATE;
     303    }
     304  }
     305
     306  rtems_status_code flip_flop_restart(void)
     307  {
     308    if (current_state == FLIP) {
     309      current_state = START;
     310
     311      return RTEMS_SUCCESSFUL;
     312    } else {
     313      return RTEMS_INCORRECT_STATE;
     314    }
     315  }
     316
     317  flip_flop_state flip_flop_current_state(void)
     318  {
     319    return current_state;
     320  }
     321
     322  rtems_status_code flip(void)
     323  {
     324    if (current_state == FLOP) {
     325      current_state = FLIP;
     326
     327      return RTEMS_SUCCESSFUL;
     328    } else {
     329      return RTEMS_INCORRECT_STATE;
     330    }
     331  }
     332
     333  rtems_status_code flop(void)
     334  {
     335    if (current_state == FLIP) {
     336      current_state = FLOP;
     337
     338      return RTEMS_SUCCESSFUL;
     339    } else {
     340      return RTEMS_INCORRECT_STATE;
     341    }
     342  }
    345343
    346344Files
    347 ^^^^^
    348 
    349 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.
     345-----
     346Document files with the ``@file`` directive omitting the optional filename
     347argument. Doxygen will infer the filename from the actual name of the file.
     348Within one Doxygen run all files are unique and specified by the current
     349Doxyfile. We can define how the generated output of path and filenames looks
     350like in the Doxyfile via the ``FULL_PATH_NAMES``, ``STRIP_FROM_PATH`` and
     351``STRIP_FROM_INC_PATH`` options.
    350352
    351353Functions
    352 ^^^^^^^^^
    353 
    354 For documentation of function arguments there are basically to ways: The first one uses @param:
    355 
    356     .. code-block::
    357 
    358         /**
    359          * @brief Copies from a source to a destination memory area.
    360          *
    361          * The source and destination areas may not overlap.
    362          *
    363          * @param[out] dest The destination memory area to copy to.
    364          * @param[in] src The source memory area to copy from.
    365          * @param[in] n The number of bytes to copy.
    366          */
    367         The second is to use @a param in descriptive text, for example:
    368 
    369         /**
    370          * Copies @a n bytes from a source memory area @a src to a destination memory
    371          * area @a dest, where both areas may not overlap.
    372          */
    373 
    374 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.
     354---------
     355
     356For documentation of function arguments there are basically to ways:
     357
     358The first one uses ``@param``:
     359
     360.. code-block:: c
     361
     362  /**
     363   * @brief Copies from a source to a destination memory area.
     364   *
     365   * The source and destination areas may not overlap.
     366   *
     367   * @param[out] dest The destination memory area to copy to.
     368   * @param[in] src The source memory area to copy from.
     369   * @param[in] n The number of bytes to copy.
     370   */
     371
     372The second is to use ``@a`` param in descriptive text, for example:
     373
     374.. code-block:: c
     375
     376  /**
     377  * Copies @a n bytes from a source memory area @a src to a destination memory
     378  * area @a dest, where both areas may not overlap.
     379  */
     380
     381The ``@a`` indicates that the next word is a function argument and deserves
     382some kind of highlighting. However, we feel that ``@a`` buries the usage of
     383function arguments within description text. In RTEMS sources, we prefer to
     384use ``@param`` instead of ``@a``.
    375385
    376386Doxyfile Hints
    377 ^^^^^^^^^^^^^^
     387--------------
    378388
    379389Header Files
    380 ------------
    381 
    382 TBD - This is out of date since the include file reorganizaiton
    383 
    384 It is an RTEMS build feature that header files need to be installed
    385 in order to be useful. One workaround to generate documentation which
    386 allows automatic link generation is to use the installed header files as
    387 documentation input. Assume that we have the RTEMS sources in the rtems
    388 directory and the build of our BSP in build/powerpc-rtems5/mybsp relative
    389 to a common top-level directory. Then you can configure Doxygen like:
    390 
    391 
    392     .. code-block::
    393 
    394         INPUT           = rtems/bsps/powerpc/mybsp \
    395                   rtems/c/src/lib/libcpu/powerpc/mycpu \
    396                   rtems/make/custom/mybsp.cfg \
    397                   build/powerpc-rtems5/mybsp/lib/include/myincludes
    398 
    399         RECURSIVE       = YES
    400 
    401         EXCLUDE         = rtems/bsps/powerpc/mybsp/include \
    402                   rtems/c/src/lib/libcpu/powerpc/mycpu/include
    403 
    404         FULL_PATH_NAMES = YES
    405 
    406         STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \
    407                   rtems
     390~~~~~~~~~~~
     391
     392It is an RTEMS build feature that header files need to be installed in order to
     393be useful. One workaround to generate documentation which allows automatic
     394link generation is to use the installed header files as documentation input.
     395Assume that we have the RTEMS sources in the rtems directory and the build of
     396our BSP in build/powerpc-rtems5/mybsp relative to a common top-level directory.
     397Then you can configure Doxygen like:
     398
     399.. code-block::
     400
     401  INPUT           = rtems/bsps/powerpc/mybsp \
     402                    rtems/c/src/lib/libcpu/powerpc/mycpu \
     403                    rtems/make/custom/mybsp.cfg \
     404                    build/powerpc-rtems5/mybsp/lib/include/myincludes
     405
     406  RECURSIVE       = YES
     407
     408  EXCLUDE         = rtems/bsps/powerpc/mybsp/include \
     409                    rtems/c/src/lib/libcpu/powerpc/mycpu/include
     410
     411  FULL_PATH_NAMES = YES
     412
     413  STRIP_FROM_PATH = build/powerpc-rtems5/mybsp/lib/include \
     414                    rtems
    408415
    409416Script and Assembly Files
    410 ^^^^^^^^^^^^^^^^^^^^^^^^^
     417~~~~~~~~~~~~~~~~~~~~~~~~~
    411418
    412419Doxygen cannot cope with script (= files with #-like comments) or assembly
    413 files. But you can add filter programs for them (TODO: Add source code
    414 for filter programs somewhere):
    415 
    416     .. code-block::
    417 
    418         FILTER_PATTERNS = *.S=c-comments-only \
    419                   *.s=c-comments-only \
    420                   *.cfg=script-comments-only \
    421                   *.am=script-comments-only \
    422                   *.ac=script-comments-only
     420files. But you can add filter programs for them
     421
     422.. COMMENT: TBD - Add source code for filter programs somewhere
     423
     424.. code-block::
     425
     426  FILTER_PATTERNS = *.S=c-comments-only \
     427                    *.s=c-comments-only \
     428                    *.cfg=script-comments-only \
     429                    *.am=script-comments-only \
     430                    *.ac=script-comments-only
    423431
    424432Assembly Example
    425 ^^^^^^^^^^^^^^^^
    426 
    427     .. code-block::
    428 
    429         /**
    430          * @fn void mpc55xx_fmpll_reset_config()
    431          *
    432          * @brief Configure FMPLL after reset.
    433          *
    434          * Sets the system clock from 12 MHz in two steps up to 128 MHz.
    435          */
    436         GLOBAL_FUNCTION mpc55xx_fmpll_reset_config
    437             /* Save link register */
    438             mflr r3
    439 
    440             LA r4, FMPLL_SYNCR
     433~~~~~~~~~~~~~~~~
     434
     435.. code-block:: c
     436
     437  /**
     438   * @fn void mpc55xx_fmpll_reset_config()
     439   *
     440   * @brief Configure FMPLL after reset.
     441   *
     442   * Sets the system clock from 12 MHz in two steps up to 128 MHz.
     443   */
     444  GLOBAL_FUNCTION mpc55xx_fmpll_reset_config
     445      /* Save link register */
     446      mflr r3
     447
     448      LA r4, FMPLL_SYNCR
    441449
    442450You have to put a declaration of this function somewhere in a header file.
    443451
    444452Script Example
    445 ^^^^^^^^^^^^^^
    446 
    447     .. code-block:: shell
    448 
    449         ##
    450         #
    451         # @file
    452         #
    453         # @ingroup mpc55xx_config
    454         #
    455         # @brief Configure script of LibBSP for the MPC55xx evaluation boards.
    456         #
    457 
    458         AC_PREREQ(2.60)
    459         AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla])
     453~~~~~~~~~~~~~~
     454
     455.. code-block:: shell
     456
     457  ##
     458  #
     459  # @file
     460  #
     461  # @ingroup mpc55xx_config
     462  #
     463  # @brief Configure script of LibBSP for the MPC55xx evaluation boards.
     464  #
     465
     466  AC_PREREQ([2.69])
     467  AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[https://devel.rtems.org/newticket])
     468
    460469
    461470GCC Attributes
    462 ^^^^^^^^^^^^^^
    463 
    464 The Doxygen C/C++ parser cannot cope with the GCC attribute((something))
    465 stuff. But you can discard such features with pre-defined preprocessor
    466 macros:
    467 
    468     .. code-block:: shell
    469 
    470         ENABLE_PREPROCESSING = YES
    471         MACRO_EXPANSION      = YES
    472         EXPAND_ONLY_PREDEF   = YES
    473         PREDEFINED           = __attribute__(x)=
     471--------------
     472
     473The Doxygen C/C++ parser cannot cope with the GCC ``attribute((something))``
     474stuff. But you can discard such features with pre-defined preprocessor macros
     475
     476.. code-block:: shell
     477
     478  ENABLE_PREPROCESSING = YES
     479  MACRO_EXPANSION      = YES
     480  EXPAND_ONLY_PREDEF   = YES
     481  PREDEFINED           = __attribute__(x)=
Note: See TracChangeset for help on using the changeset viewer.