Changeset f5c20a6 in rtems-docs


Ignore:
Timestamp:
Dec 4, 2018, 7:21:54 PM (5 months ago)
Author:
Joel Sherrill <joel@…>
Branches:
master
Children:
b8b4f14
Parents:
cd6ac10
git-author:
Joel Sherrill <joel@…> (12/04/18 19:21:54)
git-committer:
Joel Sherrill <joel@…> (12/18/18 00:45:50)
Message:

eng/coding-doxygen.rst: Clean up and make subsubsections

File:
1 edited

Legend:

Unmodified
Added
Removed
  • eng/coding-doxygen.rst

    rcd6ac10 rf5c20a6  
    1010TBD - https://devel.rtems.org/wiki/Developer/Coding/Doxygen
    1111
     12.. sidebar:: *History*
     13
     14  RTEMS is much older than Doxygen (http://www.doxygen.org/) and
     15  the documentation in the .h files was obviously not written with
     16  Doxygen markup in mind. In 2007, Joel Sherrill undertook to convert the
     17  documentation in the .h and .inl files in the RTEMS SuperCore? to Doxygen
     18  format. As a result of this effort, the Doxygen for the development
     19  version of the RTEMS is now built automatically periodically and made
     20  available on the RTEMS Website. In April 2008, Joel Sherrill began to
     21  update the Classic API (e.g. cpukit/rtems) .h files to include Doxygen
     22  markup. Now, RTEMS has nice Doxygen markup including state and sequence
     23  diagrams.
     24
    1225Doxygen Best Practices
    13 ----------------------
     26^^^^^^^^^^^^^^^^^^^^^^
    1427
    1528* Do not use @a. Instead use @param to document function parameters.
     
    2336
    2437Special 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.
     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
     42of itself if in doubt ask a mentor and/or tell a mentor the decision
     43you made.
    2844
    2945Header 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.
     46^^^^^^^^^^^^^^^^^^^
     47
     48The files *thread.h*
     49(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/thread.h)
     50and *threadimpl.h*
     51(https://git.rtems.org/rtems/tree/cpukit/score/include/rtems/score/threadimpl.h)
     52should be a good example of how a header file should be written. The
     53following gives details in bits and pieces.
    3354
    3455Header blocks
    35 -------------
     56^^^^^^^^^^^^^
    3657
    3758Header 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>`_.
    3859
    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 
    57 Header guard
    58 ------------
    59 
    60 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
    61 
    62         .. code-block:: c
    63 
    64                 #ifndef RTEMS_LIB_FLIP_FLOP_H
    65                 #define RTEMS_LIB_FLIP_FLOP_H
     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
     78Header Guard
     79^^^^^^^^^^^^
     80
     81After the comment blocks, use a header guard that assembles at
     82least 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
    6689
    6790Includes
    68 --------
     91^^^^^^^^
    6992
    7093Then add your include files before protecting C declarations from C++.
    7194
    7295
    73         .. code-block:: c
    74 
    75                 #include <rtems.h>
    76 
    77                 #ifdef __cplusplus
    78                 extern "C" {
    79                 #endif /* __cplusplus */
     96    .. code-block:: c
     97
     98        #include <rtems.h>
     99
     100        #ifdef __cplusplus
     101        extern "C" {
     102        #endif /* __cplusplus */
    80103
    81104Using @defgroup for group definitions
    82 -------------------------------------
    83 
    84 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.
    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                  */
     105^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     106
     107Add any group definitions surrounding the function declarations
     108that belong in that group. Rarely, a header may define more than one
     109group. 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         */
    112137
    113138enum and struct
    114 ---------------
    115 
    116 Provide 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;
     139^^^^^^^^^^^^^^^
     140
     141Provide documentation for declarations of enumerated types and
     142structs. 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;
    147173
    148174
    149175Using @name for organization
    150 ----------------------------
    151 
    152 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.
    153 
    154         .. code-block:: c
    155 
    156                 /**
    157                  * @name Flip-Flop Maintenance
    158                  *
    159                  * @{
    160                  */
     176^^^^^^^^^^^^^^^^^^^^^^^^^^^^
     177
     178Complicated groups can be given additional organization by using @name,
     179or by declaring additional groups within the hierarchy of the header
     180file's top-level group.
     181
     182    .. code-block:: c
     183
     184        /**
     185         * @name Flip-Flop Maintenance
     186         *
     187         * @{
     188         */
    161189
    162190Declaring functions
    163 -------------------
    164 
    165 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.
    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);
     191^^^^^^^^^^^^^^^^^^^
     192
     193Function declarations should have an @brief that states what the function
     194does in a single topic sentence starting with a descriptive verb in the
     195present 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);
    186217
    187218Do not document trivial functions, such as getter/setter methods.
    188219
    189         .. code-block:: c
    190                 flip_flop_state flip_flop_current_state(void);
     220    .. code-block:: c
     221
     222        flip_flop_state flip_flop_current_state(void);
    191223
    192224Close the documentation name definition and open a new name definition.
    193225
    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                 /** @} */
     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        /** @} */
    220253
    221254Ending the file
    222 ---------------
    223 
    224 Close 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 */
     255^^^^^^^^^^^^^^^
     256
     257Close the documentation group definition, then the extern C declarations,
     258then the header guard.
     259
     260    .. code-block:: c
     261
     262        /** @} */
     263
     264        #ifdef __cplusplus
     265        }
     266        #endif /* __cplusplus */
     267
     268        #endif /* RTEMS_LIB_FLIP_FLOP_H */
    234269
    235270No newline at the end of the file.
    236271
    237272Source 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                 }
     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        }
    310345
    311346Files
    312 -----
     347^^^^^
    313348
    314349Document 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.
    315350
    316351Functions
    317 ---------
     352^^^^^^^^^
    318353
    319354For documentation of function arguments there are basically to ways: The first one uses @param:
    320355
    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                  */
     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         */
    337373
    338374The @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.
    339375
    340376Doxyfile Hints
    341 --------------
     377^^^^^^^^^^^^^^
    342378
    343379Header Files
    344380------------
    345381
    346 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:
    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
     382TBD - This is out of date since the include file reorganizaiton
     383
     384It is an RTEMS build feature that header files need to be installed
     385in order to be useful. One workaround to generate documentation which
     386allows automatic link generation is to use the installed header files as
     387documentation input. Assume that we have the RTEMS sources in the rtems
     388directory and the build of our BSP in build/powerpc-rtems5/mybsp relative
     389to 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
    364408
    365409Script and Assembly Files
    366 -------------------------
    367 
    368 Doxygen 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
     410^^^^^^^^^^^^^^^^^^^^^^^^^
     411
     412Doxygen cannot cope with script (= files with #-like comments) or assembly
     413files. But you can add filter programs for them (TODO: Add source code
     414for 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
    376423
    377424Assembly 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
     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
    393441
    394442You have to put a declaration of this function somewhere in a header file.
    395443
    396444Script 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])
     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])
    411460
    412461GCC Attributes
    413 --------------
    414 
    415 The 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 
    423 History
    424 -------
    425 
    426 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, `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>`_.
     462^^^^^^^^^^^^^^
     463
     464The Doxygen C/C++ parser cannot cope with the GCC attribute((something))
     465stuff. But you can discard such features with pre-defined preprocessor
     466macros:
     467
     468    .. code-block:: shell
     469
     470        ENABLE_PREPROCESSING = YES
     471        MACRO_EXPANSION      = YES
     472        EXPAND_ONLY_PREDEF   = YES
     473        PREDEFINED           = __attribute__(x)=
Note: See TracChangeset for help on using the changeset viewer.