我的团队开始使用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);
我使用一个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服务器上有完整的文档，总是最新的代码。
对于需要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")
