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

当前回答

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

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

其他回答

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

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

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

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

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

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

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

使用@mainpage写一个描述性的主页(在一个单独的头文件中)。考虑一下,如我的例子所示,让它成为你的主要类/函数和模块的指南。

另一个样本

当我把上面链接的主oofile doxygen内容重新上线时,这里有一个使用Markdown格式的当前客户工作的示例。使用Markdown,您可以参考Markdown中的主页(在Doxygen设置中),这对于典型的自述me非常有用。Md文件包含在开源项目中。

Lingopal
========
Developer Documentation started when Andy Dent took over support in May 2014. 

There are a number of pages in Markdown format which explain key aspects:

- @ref doc/LingopalBuilding.md
- @ref doc/LingopalSigning.md
- @ref doc/LingopalDatabases.md
- @ref doc/LingopalExternals.md

See the <a href="pages.html">Related Pages list for more.</a>

-------------

_Note_

These pages, whilst readable by themselves, are designed to be run through the [Doxygen](http://www.doxygen.com) code documentation engine which builds an entire local cross-referenced set of docs. It uses a minor [extension of Markdown formatting.](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html)

The settings to generate the documentation are `Lingopal.doxy` and `LingopalDocOnly.doxy`. The latter is used for quick re-generation of just these additional pages.

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

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

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