我的团队开始使用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);

当前回答

如果您有一个非常非常大的项目——大到足以让Doxygen运行一个多小时——您可以将其分割成多个模块,然后Doxygen使用标记文件将其链接在一起。

例如,如果您有一个大的MSVC解决方案,其中包含20个项目,您可以让目录运行自己的Doxygen,然后使用标记文件将输出粘合在一起,就像链接器将.libs粘合在一起以生成可执行文件一样。

您甚至可以更字面地理解链接的比喻,使每个Doxy配置文件对应于一个.vcproj文件,这样每个项目(例如.lib或.dll)都得到自己的Doxy输出。

其他回答

如果您确信您的团队将遵循这样一个重量级模板,那么很好,请按照所示使用它。

否则,它看起来像JavaDoc。Doxygen的优点之一是它不需要使用如此强的标记就能很好地完成工作。你不需要使用@name,通过JAVADOC_AUTOBRIEF设置,你可以跳过@brief——只要确保注释的第一行是一个合理的简短描述。

我更喜欢描述性的名称,而不是强制的文档,并鼓励人们只在增加了重要价值时才添加注释。这样,有价值的评论就不会被所有的噪音淹没。

不要用@author或@date (@date在另一篇文章中提到过)。这些都是由修订控制系统处理的。

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

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

使用了大量的链接。这可以使用see also链接(如果您喜欢,可以使用\see或@see)来完成,并确保在文档中使用正确的类名引用其他类名。例如,如果你将FUZZYObject类引用为一个“对象”,那么在它后面立即写上类的名称(例如:“疲惫的对象(FUZZYObject)”)。

对于复杂的项目,有一个单独的模块管理文件可能很有用,它控制组和子组。整个层次结构可以在一个地方,然后每个文件可以简单地填充到子组中。例如:

/**
 * @defgroup example Top Level Example Group
 * @brief    The Example module.
 *
 * @{
 */

/**
 * @defgroup example_child1 First Child of Example
 * @brief    1st of 2 example children.
 */

/**
 * @defgroup example_child2 Second Child of Example
 * @brief    2nd of 2 example children.
 */

// @}

简单地在另一个组的{}中包含一个组的定义,使其成为该组的子组。然后在代码和头文件中,函数可以被标记为它们所在的任何组的一部分,这一切都可以在完成的文档中工作。它使得重构文档以匹配重构代码更加容易。