我的团队开始使用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命令。

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

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

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

尽可能多地使用例子。它自动将API元素链接到示例代码。

自动构建和发布您的文档。作为自动构建文档的一部分,注意警告,它很容易写出结构糟糕的注释。

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

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