我使用一个subversion post-commit钩子来提取已经更改的目录，将它们写入一个文件，然后每天晚上我自动在我们的web服务器上重新生成doxygen html，这样我们总是有最新的docco。

我想要记录的每个项目都有一个小项目。Doxy文件，包含每个项目的设置和一个包含到主doxygen设置-例如:

PROJECT_NAME           = "AlertServer"
PROJECT_NUMBER         = 8.1.2
INPUT                  = "C:/Dev/src/8.1.2/Common/AlertServer"
HTML_OUTPUT            = "AlertServer"
@INCLUDE = "c:\dev\CommonConfig.doxy"

对于Windows SVN服务器，使用钩子:

@echo off
for /F "eol=¬ delims=¬" %%A in ('svnlook dirs-changed %1 -r %2') do echo %%A >> c:\svn_exports\export.txt

然后每晚运行:

@echo off

rem ---------------
rem remove duplicates.
type nul> %TEMP%.\TEMP.txt

for /F "eol=¬ delims=¬" %%a in (c:\svn_exports\export.txt) do (
 findstr /L /C:"%%a" < %TEMP%.\TEMP.txt > nul
 if errorlevel=1 echo %%a>> %TEMP%.\TEMP.txt
)

copy /y %TEMP%.\TEMP.txt export_uniq.cmd >nul
if exist %TEMP%.\TEMP.txt del %TEMP%.\TEMP.txt


rem ---------------
rem fetch all the recently changed directories into the svn_exports directory

for /F "eol=¬ delims=¬" %%A in (c:\svn_exports\export_uniq.cmd) do (
  svn export "file:///d:/repos/MyRepo/%%A" "c:/svn_exports/%%A"  --force 
)


rem ---------------
rem search through all dirs for any config files, if found run doxygen

for /R c:\svn_exports %%i in (*.doxy) do c:\tools\doxygen\bin\doxygen.exe "%i"


rem ---------------
rem now remove the directories to be generated.
del /F c:\svn_exports

这将删除重复的条目，找到具有.doxy项目文件的所有项目，并在它们上运行doxygen。瞧:在web服务器上有完整的文档，总是最新的代码。

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

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

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

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

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

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

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES

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

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

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

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