= Doxygen Recommendations = = Best Practice = * Do not use ''@param''. Instead use ''@a name'' to document function parameters. * Do not use ''@return''. * Use ''@retval'' to document return status codes. * Do not write documentation for trivial functions. * Use groups and arrange them in a hierarchy. * Put every file into at least one group. * Do not use ''@note''. * Use dot comments for state diagrams. * Do not repeat documentation, use ''@see'' for example. = Header File Example = {{{ /** * @file * * @ingroup FlipFlop * * @brief Flip-Flop API. */ /* * Copyright (c) YYYY Author. * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.com/license/LICENSE. * * $Id$ */ #ifndef FLIP_FLOP_H #define FLIP_FLOP_H #include #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /** * @defgroup FlipFlop Flip-Flop * * @brief Simple Flip-Flop state machine. * * @dot * digraph { * start [label="START"]; * flip [label="FLIP"]; * flop [label="FLOP"]; * flip -> flop [label="flop()", URL="\ref flop"]; * flop -> flip [label="flip()", URL="\ref flip"]; * start -> flip * [label="flip_flop_initialize(FLIP)", URL="\ref flip_flop_initialize"]; * start -> flop * [label="flip_flop_initialize(FLOP)", URL="\ref flip_flop_initialize"]; * flip -> start * [label="flip_flop_restart()", URL="\ref flip_flop_restart"]; * } * @enddot * * @{ */ typedef enum { START = 0, FLIP, FLOP } flip_flop_state; /** * @name Flip-Flop Maintanance * * @{ */ /** * @brief Initializes the flip-flop in the state @a state. * * @retval RTEMS_SUCCESSFUL Successfully initialized. * @retval RTEMS_INCORRECT_STATE Flip-flopios eCos for Nios Zylin Embedded CDT Zylin CPU Eclipse CDT plugin | Eclipse update site | Mini FAQ Zylin Embedded CDT Zylin-embedded CDT not in start state. */ rtems_status_code flip_flop_initialize(flip_flop_state state); /** * @brief Restarts the flip-flop. * * @retval RTEMS_SUCCESSFUL Successfully restarted. * @retval RTEMS_INCORRECT_STATE Flip-flop not in flip state. */ rtems_status_code flip_flop_restart(void); flip_flop_state flip_flop_current_state(void); /** @} */ /** * @name Flip-Flop Usage * * @{ */ /** * @brief Flip operation. * * @retval RTEMS_SUCCESSFUL Flipped successfully. * @retval RTEMS_INCORRECT_STATE Incorrect state for flip operation. */ rtems_status_code flip(void); /** * @brief Flop operation. * * @retval RTEMS_SUCCESSFUL Flopped successfully. * @retval RTEMS_INCORRECT_STATE Incorrect state for flop operation. */ rtems_status_code flop(void); /** @} */ /** @} */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* FLIP_FLOP_H */ }}} = Source File Example = {{{ /** * @file * * @ingroup FlipFlop * * @brief Flip-Flop implementation. */ /* * Copyright (c) YYYY Author. * * The license and distribution terms for this file may be * found in the file LICENSE in this distribution or at * http://www.rtems.com/license/LICENSE. * * $Id$ */ #include "flip-flop.h" static flip_flop_state current_state; rtems_status_code flip_flop_initialize(flip_flop_state state) { if (current_state == START) { current_state = state; return RTEMS_SUCCESSFUL; } else { return RTEMS_INCORRECT_STATE; } } rtems_status_code flip_flop_restart(void) { if (current_state == FLIP) { current_state = START; return RTEMS_SUCCESSFUL; } else { return RTEMS_INCORRECT_STATE; } } flip_flop_state flip_flop_current_state(void) { return current_state; } rtems_status_code flip(void) { if (current_state == FLOP) { current_state = FLIP; return RTEMS_SUCCESSFUL; } else { return RTEMS_INCORRECT_STATE; } } rtems_status_code flop(void) { if (current_state == FLIP) { current_state = FLOP; return RTEMS_SUCCESSFUL; } else { return RTEMS_INCORRECT_STATE; } } }}} = Files = You can document a file with the ''@file [filename]'' directive. If you omit the filename Doxygen will use it for the documentation of the file containing this directive. This is the preferred way to document files which can be read by Doxygen. You should not use ''@file name_of_current_file'' to document the current file because this instructs Doxygen to document a file with the filename ''name_of_current_file'' and this is not necessarily the current one and may lead to ambiguity if someone from outside reuses your stuff to generate her documentation. Within one Doxygen run all files are unique and specified by the current Doxyfile. You 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. = Functions = For documentation of function arguments there are basically to ways: The first one uses @param: {{{ /** * Copies bytes from a source memory area to a destination memory area, * where both areas may not overlap. * @param[out] dest The memory area to copy to. * @param[in] src The memory area to copy from. * @param[in] n The number of bytes to copy. */ }}} This leads likely to copy&paste within the comment, bloats simple function comments and is not very fluent to read. One alternative is this: {{{ /** * Copies @a n bytes from a source memory area @a src to a destination memory * area @a dest, where both areas may not overlap. */ }}} The @a indicates that the next word is a function argument and deserves some kind of high-lightning. = Doxyfile Hints = = Header Files = It is a 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-rtems4.9/mybsp'' relative to a common top level directory. Then you can configure Doxygen like: {{{ INPUT = rtems/c/src/lib/libbsp/powerpc/mybsp \ rtems/c/src/lib/libcpu/powerpc/mycpu \ rtems/make/custom/mybsp.cfg \ build/powerpc-rtems4.9/mybsp/lib/include/myincludes RECURSIVE = YES EXCLUDE = rtems/c/src/lib/libbsp/powerpc/mybsp/include \ rtems/c/src/lib/libcpu/powerpc/mycpu/include FULL_PATH_NAMES = YES STRIP_FROM_PATH = build/powerpc-rtems4.9/mybsp/lib/include \ rtems }}} = Script and Assembly Files = 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): {{{ FILTER_PATTERNS = *.S=c-comments-only \ *.s=c-comments-only \ *.cfg=script-comments-only \ *.am=script-comments-only \ *.ac=script-comments-only }}} == Assembly Example == {{{ /** * @fn void mpc55xx_fmpll_reset_config() * * @brief Configure FMPLL after reset. * * Sets the system clock from 12 MHz in two steps up to 128 MHz. */ GLOBAL_FUNCTION mpc55xx_fmpll_reset_config /* Save link register */ mflr r3 LA r4, FMPLL_SYNCR }}} You have to put a declaration of this function somewhere in a header file. == Script Example == {{{ ## # # @file # # @ingroup mpc55xx_config # # @brief Configure script of LibBSP for the MPC55xx evaluation boards. # AC_PREREQ(2.60) AC_INIT([rtems-c-src-lib-libbsp-powerpc-mpc55xxevb],[_RTEMS_VERSION],[http://www.rtems.org/bugzilla]) }}} = GCC Attributes = The Doxygen C/C++ parser cannot cope with the GCC __attribute__((something)) stuff. But you can discard such features with pre-defined preprocessor macros: {{{ ENABLE_PREPROCESSING = YES MACRO_EXPANSION = YES EXPAND_ONLY_PREDEF = YES PREDEFINED = __attribute__(x)= }}} = History = RTEMS is much older than [http://www.doxygen.org Doxygen] and the documentation in the .h and .inl files was obviously not written with [http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen markup]. In 2007, [wiki:TBR/User/JoelSherrill JoelSherrill] undertook converting 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 CVS version of the RTEMS SuperCore is now built automatically multiple times per day and made available on the RTEMS Website. In April 2008, [wiki:TBR/User/JoelSherrill JoelSherrill] began to update the Classic API (e.g. cpukit/rtems) .h and .inl files to include [http://www.stack.nl/~dimitri/doxygen/manual.html Doxygen markup].