使用doxygen记录代码的最佳技巧?

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

当前回答

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

2009-10-18 03:47:29

其他回答

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

2009-12-30 15:40:22

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

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

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

2009-01-14 22:43:12

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

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

2009-05-22 00:20:46

如果您发现配置指令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指令上。

2015-12-03 20:10:50

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

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

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

2008-11-14 11:10:04

使用doxygen记录代码的最佳技巧?

推荐文章

最新文章

标签