对于需要5分钟以上生成的大型项目，我发现能够快速为单个文件生成doxygen并在web浏览器中查看它非常有用。

虽然对文件外部任何内容的引用都不会解析，但查看基本格式是否正确仍然是有用的。

这个脚本使用一个文件和项目doxy配置并运行doxygen，我已经将其设置为从我的IDE运行。

#!/usr/bin/env python3
"""
This script takes 2-3 args: [--browse] <Doxyfile> <sourcefile>

  --browse will open the resulting docs in a web browser.
"""
import sys
import os
import subprocess
import tempfile

doxyfile, sourcefile = sys.argv[-2:]

tempfile = tempfile.NamedTemporaryFile(mode='w+b')
doxyfile_tmp = tempfile.name
tempfile.write(open(doxyfile, "r+b").read())
tempfile.write(b'\n\n')
tempfile.write(b'INPUT=' + os.fsencode(sourcefile) + b'\n')
tempfile.flush()

subprocess.call(("doxygen", doxyfile_tmp))
del tempfile

# Maybe handy, but also annoying as default.
if "--browse" in sys.argv:
    import webbrowser
    webbrowser.open("html/files.html")

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

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

如果您担心一些团队成员会避免使用文档，或者您只是想要一个最小的文档集，那么您可以在doxygen配置中启用这些。

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES

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

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

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

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

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

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