我的团队开始使用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来描述我们对一些私有成员所做的事情。
对于需要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")
使用@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.
你不需要也不应该在@file指令中写入文件名，doxygen会自动读取文件名。写文件名的问题是，当你重命名文件时，你也必须改变@file指令。
提供@author和@date信息在大多数情况下也是无用的，因为源代码控制系统做得比手动编辑文件要好得多。
如果你使用以下Doxygen语法并在Doxygen的配置中启用JAVADOC_AUTOBRIEF，你也不必写@brief:
/*! Short Description on the first line
Detailed description...
...
*/
void foo(void) {}
函数的@name指令在大多数时候也是100%冗余的，完全无用。它只在有人修改函数名而不是doxygen @name时才会带来错误。
