Changes between Version 14 and Version 15 of Developer/Coding/Doxygen
- Timestamp:
- 12/16/12 19:22:07 (11 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
Developer/Coding/Doxygen
v14 v15 4 4 5 5 6 * Do not use ''@ param''. Instead use ''@a name'' to document function parameters.6 * Do not use ''@a''. Instead use ''@param'' to document function parameters. 7 7 * Do not use ''@return''. Instead use ''@retval'' to document return status codes. 8 8 * Do not write documentation for trivial functions. … … 131 131 {{{ 132 132 /** 133 * @brief Initializes the flip-flop in the state @astate.133 * @brief Initializes the flip-flop state. 134 134 * 135 135 * @param[in] state The initial state to set the flip-flop. … … 278 278 {{{ 279 279 /** 280 * Copies bytes from a source memory area to a destination memory area, 281 * where both areas may not overlap. 282 * @param[out] dest The memory area to copy to. 283 * @param[in] src The memory area to copy from. 280 * @brief Copies from a source to a destination memory area. 281 * 282 * The source and destination areas may not overlap. 283 * 284 * @param[out] dest The destination memory area to copy to. 285 * @param[in] src The source memory area to copy from. 284 286 * @param[in] n The number of bytes to copy. 285 287 */ 286 288 }}} 287 289 288 This leads likely to copy&paste within the comment, bloats simple function comments and is not very fluent to read. 289 290 One alternative is this: 290 The second is to use @a param in descriptive text, for example 291 291 {{{ 292 292 /** … … 296 296 }}} 297 297 298 The @a indicates that the next word is a function argument and deserves some kind of high-light ning.298 The @a indicates that the next word is a function argument and deserves some kind of high-lighting. 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. 299 299 = Doxyfile Hints = 300 300