使用@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.

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

对于需要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")

对于复杂的项目，有一个单独的模块管理文件可能很有用，它控制组和子组。整个层次结构可以在一个地方，然后每个文件可以简单地填充到子组中。例如:

/**
 * @defgroup example Top Level Example Group
 * @brief    The Example module.
 *
 * @{
 */

/**
 * @defgroup example_child1 First Child of Example
 * @brief    1st of 2 example children.
 */

/**
 * @defgroup example_child2 Second Child of Example
 * @brief    2nd of 2 example children.
 */

// @}

简单地在另一个组的{}中包含一个组的定义，使其成为该组的子组。然后在代码和头文件中，函数可以被标记为它们所在的任何组的一部分，这一切都可以在完成的文档中工作。它使得重构文档以匹配重构代码更加容易。

你不需要也不应该在@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时才会带来错误。

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