Changes between Version 9 and Version 10 of Developer/Coding/Doxygen
- Timestamp:
- 12/15/12 19:15:32 (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Developer/Coding/Doxygen
v9 v10 13 13 = Header File Example = 14 14 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 18 Header files should contain the similar comment blocks as other source files, described at [wiki:Coding_Conventions#File_Issues Coding Conventions#File Issues]. 15 19 {{{ 16 20 /** … … 30 34 */ 31 35 32 #ifndef FLIP_FLOP_H 33 #define FLIP_FLOP_H 34 36 }}} 37 38 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 39 {{{ 40 #ifndef RTEMS_LIB_FLIP_FLOP_H 41 #define RTEMS_LIB_FLIP_FLOP_H 42 43 }}} 44 45 Then add your include files before protecting C declarations from C++. 46 {{{ 35 47 #include <rtems.h> 36 48 … … 39 51 #endif /* __cplusplus */ 40 52 53 }}} 54 55 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. 56 {{{ 41 57 /** 42 58 * @defgroup FlipFlop Flip-Flop … … 63 79 */ 64 80 81 }}} 82 83 Provide 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 */ 65 90 typedef enum { 66 91 START = 0, … … 70 95 71 96 /** 72 * @name Flip-Flop Maintanance 97 * @brief Object containing multiple flip-flops. 98 * 99 * Encapsulates multiple flip-flops. 100 */ 101 typedef 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 113 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. 114 {{{ 115 /** 116 * @name Flip-Flop Maintenance 73 117 * 74 118 * @{ 75 119 */ 76 120 121 }}} 122 123 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. 124 {{{ 77 125 /** 78 126 * @brief Initializes the flip-flop in the state @a state. 79 127 * 128 * @param[in] state The initial state to set the flip-flop. 129 * 80 130 * @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. 89 132 */ 90 133 rtems_status_code flip_flop_initialize(flip_flop_state state); … … 98 141 rtems_status_code flip_flop_restart(void); 99 142 143 }}} 144 145 Do not document trivial functions, such as getter/setter methods. 146 {{{ 100 147 flip_flop_state flip_flop_current_state(void); 101 148 149 }}} 150 151 Close the documentation name definition and open a new name definition. 152 {{{ 102 153 /** @} */ 103 154 … … 114 165 * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. 115 166 */ 116 rtems_status_code flip( void);167 rtems_status_code flip( void ); 117 168 118 169 /** … … 122 173 * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. 123 174 */ 124 rtems_status_code flop( void);175 rtems_status_code flop( void ); 125 176 126 177 /** @} */ 127 178 179 }}} 180 181 Close the documentation group definition, then the extern C declarations, then the header guard. 182 {{{ 128 183 /** @} */ 129 184 … … 132 187 #endif /* __cplusplus */ 133 188 134 #endif /* FLIP_FLOP_H */ 135 }}} 189 #endif /* RTEMS_LIB_FLIP_FLOP_H */ 190 }}} 191 No newline at the end of the file 136 192 = Source File Example = 137 193 … … 151 207 * found in the file LICENSE in this distribution or at 152 208 * http://www.rtems.com/license/LICENSE. 153 * 154 * $Id$ 155 */ 156 157 #include "flip-flop.h" 209 */ 210 211 #include <rtems/lib/flipflop.h> 158 212 159 213 static flip_flop_state current_state;