📒 代码风格

Doxygen

Quote

• Doxygen Quick Reference

Info

• StackOverflow: Where to put the doxygen comment blocks for an internal library - in H or in CPP files?
• 这是一个使用 Doxygen 的小型 C 项目，值得参考：GitHub: libcsv

配置与运行

Doxygen 的配置文件较为复杂，这里总结一些经常实用的配置项：

• PROJECT_NAME
• INPUT：指定源文件的路径。
• GENERATE_HTML：是否生成 HTML 文档。
• FULL_PATH_NAMES：在文档中显示完整路径名。默认为 YES，此时文档的 File Documentation 等处将显示源文件的绝对路径，可能暴露用户名字等信息。建议设置为 No，以免暴露路径信息。
• COMPACT_LATEX：生成紧凑的 LaTeX 文档，将去除空白页面、不将目录与内容页面分开等。

编写注释

注释放置在头文件还是源文件？

一般来说，头文件尽量保持简洁，不放置注释或仅放置说明接口信息的注释。详细（实现细节）的注释放置在源文件中。

这样的好处：头文件中的注释一旦发生变动，会导致所有引用该头文件的源文件都被重新编译。而源文件中的注释变动不会导致其他源文件重新编译。

mymodule.h

/**
 * @brief This method adds two integers.
 * @param[in] a First integer to add.
 * @param[in] b Second integer to add.
 * @return The sum of both parameters.
 */
int add(int a, int b);

mymodule.cpp

/**
 * This method uses a little-known variant of integer addition known as
 * Sophocles' Scissors. It optimises the function's performance on many
 * platforms that we may or may not choose to target in the future.
 * @TODO make sure I implemented the algorithm correctly with some unit tests.
 */
int add(int a, int b) {
  return b + a;
}

常用的注释格式：

• 为整个文件编写注释：

  /**
   * @file mymodule.h
   * @brief This file contains the declaration of the add function.
   */
  

• 为函数编写注释：

  ```c /* * @brief This method adds two integers. * @param[in] a First integer to add. * @param[in] b Second integer to add. * @return The sum of both parameters. /

• 为数据结构编写注释：

  /**
   * @brief A structure representing a point in 2D space.
   */
  struct Point {
    int x; /**< The x-coordinate of the point. */
    int y; /**< The y-coordinate of the point. */
  };
  

• 将一部分注释结合成组：

  /**
   * @defgroup math Math functions
      * @{
      */
  
  // ...
  
  /**
   * @}
   */