Changes between Version 9 and Version 10 of Developer/Coding/Doxygen


Ignore:
Timestamp:
Dec 15, 2012, 7:15:32 PM (7 years ago)
Author:
Gedare
Comment:

Update header example

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Coding/Doxygen

    v9 v10  
    1313=  Header File Example  =
    1414
     15[wiki:File:foobar.h File:foobar.h] is an example of how a header file should be written. The following gives details in bits and pieces.
     16=  Header blocks  =
     17
     18Header files should contain the similar comment blocks as other source files, described at [wiki:Coding_Conventions#File_Issues Coding Conventions#File Issues].
    1519{{{
    1620/**
     
    3034 */
    3135
    32 #ifndef FLIP_FLOP_H
    33 #define FLIP_FLOP_H
    34 
     36}}}
     37
     38After 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
     39{{{
     40#ifndef RTEMS_LIB_FLIP_FLOP_H
     41#define RTEMS_LIB_FLIP_FLOP_H
     42
     43}}}
     44
     45Then add your include files before protecting C declarations from C++.
     46{{{
    3547#include <rtems.h>
    3648
     
    3951#endif /* __cplusplus */
    4052
     53}}}
     54
     55Add 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.
     56{{{
    4157/**
    4258 * @defgroup FlipFlop Flip-Flop
     
    6379 */
    6480
     81}}}
     82
     83Provide documentation for declarations of enumerated types and structs. Use typedefs for structs, and do not use _t as a typename suffix.
     84{{{
     85/**
     86 * @brief The set of possible flip-flop states.
     87 *
     88 * Enumerated type to define the set of states for a flip-flop.
     89 */
    6590typedef enum {
    6691  START = 0,
     
    7095
    7196/**
    72  * @name Flip-Flop Maintanance
     97 * @brief Object containing multiple flip-flops.
     98 *
     99 * Encapsulates multiple flip-flops.
     100 */
     101typedef struct {
     102  /**
     103   * @brief Primary flip-flop.
     104   */
     105  flip_flop_state primary;
     106  /**
     107   * @brief Secondary flip-flop.
     108   */
     109  flip_flop_state secondary;
     110} flip_flop_multiple;
     111}}}
     112
     113Complicated 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.
     114{{{
     115/**
     116 * @name Flip-Flop Maintenance
    73117 *
    74118 * @{
    75119 */
    76120
     121}}}
     122
     123Function 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.
     124{{{
    77125/**
    78126 * @brief Initializes the flip-flop in the state @a state.
    79127 *
     128 * @param[in] state The initial state to set the flip-flop.
     129 *
    80130 * @retval RTEMS_SUCCESSFUL Successfully initialized.
    81  * @retval RTEMS_INCORRECT_STATE Flip-flopios
    82 eCos for Nios
    83 Zylin Embedded CDT
    84 Zylin CPU
    85        
    86 Eclipse CDT plugin | Eclipse update site | Mini FAQ
    87 Zylin Embedded CDT
    88 Zylin-embedded CDT not in start state.
     131 * @retval RTEMS_INCORRECT_STATE Flip-flop state is not valid.
    89132 */
    90133rtems_status_code flip_flop_initialize(flip_flop_state state);
     
    98141rtems_status_code flip_flop_restart(void);
    99142
     143}}}
     144
     145Do not document trivial functions, such as getter/setter methods.
     146{{{
    100147flip_flop_state flip_flop_current_state(void);
    101148
     149}}}
     150
     151Close the documentation name definition and open a new name definition.
     152{{{
    102153/** @} */
    103154
     
    114165 * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation.
    115166 */
    116 rtems_status_code flip(void);
     167rtems_status_code flip( void );
    117168
    118169/**
     
    122173 * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation.
    123174 */
    124 rtems_status_code flop(void);
     175rtems_status_code flop( void );
    125176
    126177/** @} */
    127178
     179}}}
     180
     181Close the documentation group definition, then the extern C declarations, then the header guard.
     182{{{
    128183/** @} */
    129184
     
    132187#endif /* __cplusplus */
    133188
    134 #endif /* FLIP_FLOP_H */
    135 }}}
     189#endif /* RTEMS_LIB_FLIP_FLOP_H */
     190}}}
     191No newline at the end of the file
    136192=  Source File Example  =
    137193
     
    151207 * found in the file LICENSE in this distribution or at
    152208 * http://www.rtems.com/license/LICENSE.
    153  *
    154  * $Id$
    155  */
    156 
    157 #include "flip-flop.h"
     209 */
     210
     211#include <rtems/lib/flipflop.h>
    158212
    159213static flip_flop_state current_state;