我的团队开始使用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配置中启用这些。

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES

作为doxygen构建过程的一部分,将警告保存到一个文件中,并尝试获得并保持警告计数尽可能低(如果合理则为0)。如果这样做,每个公共和受保护类成员将至少需要一个@brief,每个函数参数的@param和一个@return。这足以描述大多数api,而不会过多妨碍其他活跃的代码库。

当然,您应该鼓励人们在每个案例的基础上尽可能多地记录他们认为需要的文档,只要他们满足最低的项目标准。但是不要将最小值设置得太高,否则最终可能得不到有用的文档。

例如,在我们的项目中,其他程序员可能接触到的所有内容都应该被记录。启用警告,让我们看看我们有多接近这个目标。我们还尝试使用@internal来描述我们对一些私有成员所做的事情。

其他回答

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

当我发现自己在高分辨率的屏幕上编辑代码时,我已经从使用反斜杠转向使用@前缀的Doxygen命令。不那么嘈杂的反斜杠发现自己现在太难以分辨出Doxygen命令。

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

总是在类中包含描述。试着说明一个类是如何使用的,或者为什么使用它,而不仅仅是它是什么(通常只是反映了名称)。

使用组将代码组织成模块。

请记住,您可以将几乎所有内容放到多个组中,以便它们可以用于提供语义标记,就像Stack Overflow中的标记一样。例如,可以将内容标记为特定于给定平台的内容。

您还可以使用组来匹配IDE中的文件夹层次结构,如我的RB2Doxy示例输出所示。

组在嵌套时工作得很好——我有一个OOFILE源代码的大示例。