我的团队开始使用doxygen记录我们的C代码,特别注意我们的公共API头文件。在doxygen中似乎有很大的灵活性和不同的特殊命令,这很好,但不经过反复试验就不清楚什么是好东西,什么是坏东西。

你最喜欢用什么方法来标记你的代码,你必须做什么和不做什么? 请提供您的最佳建议,每个答案一个,以方便投票。

我希望定义API文档的整个方法,包括提供一个模板让团队的其他成员开始工作。到目前为止,我有这样的东西:

/**
 * @file   example_action.h
 * @Author Me (me@example.com)
 * @date   September, 2008
 * @brief  Brief description of file.
 *
 * Detailed description of file.
 */

/**
 * @name    Example API Actions
 * @brief   Example actions available.
 * @ingroup example
 *
 * This API provides certain actions as an example.
 *
 * @param [in] repeat  Number of times to do nothing.
 *
 * @retval TRUE   Successfully did nothing.
 * @retval FALSE  Oops, did something.
 *
 * Example Usage:
 * @code
 *    example_nada(3); // Do nothing 3 times.
 * @endcode
 */
boolean example(int repeat);

当前回答

如果您发现配置指令INLINE_SOURCES在文档中放置了太多代码,您可以使用\snippet命令手动引用代码的特定部分。

  /**
   * Requirment XYZ is implemented by the following code.
   * 
   * \snippet file.c CODE_LABEL
   */
  int D() 
  {
     //[CODE_LABEL]
     if( A )
     {
        B= C();
     }
     //[CODE_LABEL]
  }

注意:snippet从EXAMPLE_PATH获取文件,而不是源路径。您必须将INPUT指令中的文件和路径列表放在EXAMPLE_PATH指令上。

其他回答

如果你在代码中有bug,或者你发现了bug,你也可以像这样在代码中标记:

/** @bug The text explaining the bug */

当你运行doxygen时,你会得到一个单独的Bug列表和待办事项列表

我在代码中使用的一些命令:

为了跟踪待办事项,将在最终文档中创建一个包含待办事项列表的页面。 \c <word>显示使用打字机字体的参数。使用它来引用一个代码字。在你的例子中,我会在“TRUE”和“FALSE”之前使用它。 \a, \警告,\see:详细描述见http://www.stack.nl/~dimitri/doxygen/commands.html#cmdc

你不需要也不应该在@file指令中写入文件名,doxygen会自动读取文件名。写文件名的问题是,当你重命名文件时,你也必须改变@file指令。

提供@author和@date信息在大多数情况下也是无用的,因为源代码控制系统做得比手动编辑文件要好得多。

如果你使用以下Doxygen语法并在Doxygen的配置中启用JAVADOC_AUTOBRIEF,你也不必写@brief:

/*! Short Description on the first line

    Detailed description...
    ...
*/
void foo(void) {}

函数的@name指令在大多数时候也是100%冗余的,完全无用。它只在有人修改函数名而不是doxygen @name时才会带来错误。

如果使用\defgroup对成员函数和字段进行分组有意义的话。这是非常有用的,即使你说得不多。

一个好的“最佳实践”(虽然并不总是可以实现)是为每个API提供简短的工作示例,并使用\ inclelineno(或\include表示没有行号)将它们拉入帮助。这些可以是单元测试,如果它们的编写是为了让用户能够理解它们(也就是说,没有连接到更大的测试工具中)。作为一个不错的副作用,对API的更改将破坏样本,因此它们必须保持最新。

你可以用文字来描述API,但是没有什么比看到实际的代码来理解如何使用它更好的了。