Doxygen - 治好了我的代码注释强迫症

在编写大量代码时，或者与多人协作进行开发时，文字记录很重要（文档或注释），尤其对于开发者本人回顾之前写过的代码和 code reviewer 查看。目前，代码中的注释进是程序员们最经常使用的记录方法。但是，由于每个人的注释风格不同，有些开发者甚至对API并不进行任何注释描述，导致很多影响生产效率的问题，也增加了软件维护的成本。很多人对于怎样写注释也会困惑和反感。因此，使用一些代码文档工可以帮助这个开发流程高效、规范地进行。

使用这种工具我个人认为最大的帮助是可以节省时间，并提高生产力：

• 不用去构思如何去写注释，用哪一种风格去写，从而专注于构思代码。
• 减少看其他人代码的时间成本。

Doxygen 就是这样一种编写软件参考文档的工具。该文档是直接以注释的形式写在代码中的，因此比较容易修改和查看。而且对于代码里的注释，Doxygen还可以为C++项目生成html，Latex和PDF的文档。

虽然使用过Doxygen的开发者可能并不会经常阅读由Doxygen生成的那些文档，而是更加倾向于阅读源代码里的注释。但是并不妨碍Doxygen成为一款很受欢迎而且高效的代码注释工具，至少我个人很喜欢Doxygen对于注释的种种规范。

关于如何使用Dxygen的适用方法，可以参照官方的教程，不会有比这个更加权威并且详细的说明了：https://www.doxygen.nl/manual/index.html。

在之前分享过的C/C++ Coding Style（https://qizongwu.com/posts/coding-style）中，我介绍了使用Doxygen进行代码注释的一些风格，在这里详细介绍一些我经常使用的Doxygen属性。

一个例子

例如一个头文件中：

/***************************************************************************** * Portfolio Info ****************************************************************************//** * @file doxygen.h * @brief File containing example of doxygen usage for quick reference. * * Here typically goes a more extensive explanation of what the header * defines. Doxygens tags are words preceeded by either a backslash @\\ * or by an at symbol @@. * * @author Chris Wu * @date 24 Oct 2019 * @see  *//** @addtogroup DOXYGEN_API * @brief Doxygen api example. * * Detailed api description. * * @{ */#ifndef _TEMP_DOXYGEN_H#define _TEMP_DOXYGEN_H#ifdef __cplusplusextern "C" {#endif/* INCLUDE FILES */#include //#include //#include "local_header1.h"//#include "local_header2.h"/* GLOBAL DEFINES *//** * @brief Use brief, otherwise the index won't have a brief explanation. * * Detailed explanation. */typedef enum eEnumMode{    ENUM_FIRST,  /**< Some documentation for first. */    BOXENUM_SECOND, /**< Some documentation for second. */    BOXENUM_ETC     /**< Etc. */} tEnumMode;/** * @brief Use brief, otherwise the index won't have a brief explanation. * * Detailed explanation. */typedef struct BoxStruct{    int a;    /**< Some documentation for the member BoxStruct#a. */    int b;    /**< Some documentation for the member BoxStruct#b. */    double c; /**< Etc. */} tBoxStruct;/* GLOBAL VARIABLES */extern int giValue;/* GLOBAL FUNCTIONS *//** * @brief Example showing how to document a function with Doxygen. * * Description of what the function does. This part may refer to the parameters * of the function, like @p param1 or @p param2. A word of code can also be * inserted like @c this which is equivalent to this and can be useful * to say that the function returns a @c void or an @c int. If you want to have * more than one word in typewriter font, then just use @. * We can also include text verbatim, * when the language is not the one used in the current source file (but * be careful as this may be supported only by recent versions * of Doxygen). By the way, this is how you write bold text or, * if it is just one word, then you can just do @b this. * * @param [in] param1 Description of the first parameter of the function. * @param [out] param2 The second one, which follows @p param1, and represents output. * * @return Describe what the function returns. * @retval XXX_OK if successful. * * @see doxygen_theSecondFunction * @see Box_The_Last_One * @see  * @note Something to note. * @warning Warning. */int doxygen_theFirstFunction(int param1, int param2);/** * @brief A simple stub function to show how links do work. * * Links are generated automatically for webpages (like ) * and for structures, like sBoxStruct. For typedef-ed types use * #tBoxStruct. * For functions, automatic links are generated when the parenthesis () follow * the name of the function, like doxygen_theFirstFunction(). * Alternatively, you can use #doxygen_theFirstFunction. * @return @c NULL is always returned. */void doxygen_theSecondFunction(void);#ifdef __cplusplus}#endif#endif /* _TEMP_DOXYGEN_H *//** @}*/

/***************************************************************************** * Portfolio Info ****************************************************************************/

/** * @file header.h * @brief Brief file introduction. * * Detailed file introduction. * * @author Name * @date day month year * @see Related link. */

/** @addtogroup DOXYGEN_API * @brief Doxygen api example. * * Detailed api description. * * @{ */

/** @}*/

/** * @brief Use brief, otherwise the index won't have a brief explanation. * * Detailed explanation. */typedef struct BoxStruct{    int a;    /**< Some documentation for the member BoxStruct#a. */    int b;    /**< Some documentation for the member BoxStruct#b. */    double c; /**< Etc. */} tBoxStruct;

/* GLOBAL FUNCTIONS *//** * @brief Example showing how to document a function with Doxygen. * * Description of what the function does. This part may refer to the parameters * of the function, like @p param1 or @p param2. A word of code can also be * inserted like @c this which is equivalent to this and can be useful * to say that the function returns a @c void or an @c int. If you want to have * more than one word in typewriter font, then just use @. * We can also include text verbatim, * when the language is not the one used in the current source file (but * be careful as this may be supported only by recent versions * of Doxygen). By the way, this is how you write bold text or, * if it is just one word, then you can just do @b this. * * @param [in] param1 Description of the first parameter of the function. * @param [out] param2 The second one, which follows @p param1, and represents output. * * @return Describe what the function returns. * @retval XXX_OK if successful. * * @see doxygen_theSecondFunction * @see Box_The_Last_One * @see  * @note Something to note. * @warning Warning. */int doxygen_theFirstFunction(int param1, int param2);