使用doxygen记录代码的最佳技巧?

我的团队开始使用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);

当前回答

使用了大量的链接。这可以使用see also链接(如果您喜欢，可以使用\see或@see)来完成，并确保在文档中使用正确的类名引用其他类名。例如，如果你将FUZZYObject类引用为一个“对象”，那么在它后面立即写上类的名称(例如:“疲惫的对象(FUZZYObject)”)。

2009-10-18 03:47:29

其他回答

我在代码中使用的一些命令:

为了跟踪待办事项，将在最终文档中创建一个包含待办事项列表的页面。 \c <word>显示使用打字机字体的参数。使用它来引用一个代码字。在你的例子中，我会在“TRUE”和“FALSE”之前使用它。 \a， \警告，\see:详细描述见http://www.stack.nl/~dimitri/doxygen/commands.html#cmdc

2008-09-09 13:39:12

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

WARNINGS               = YES
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES

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

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

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

2011-01-23 23:08:24

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

2012-09-13 13:58:42

如果您有一个非常非常大的项目——大到足以让Doxygen运行一个多小时——您可以将其分割成多个模块，然后Doxygen使用标记文件将其链接在一起。

例如，如果您有一个大的MSVC解决方案，其中包含20个项目，您可以让目录运行自己的Doxygen，然后使用标记文件将输出粘合在一起，就像链接器将.libs粘合在一起以生成可执行文件一样。

您甚至可以更字面地理解链接的比喻，使每个Doxy配置文件对应于一个.vcproj文件，这样每个项目(例如.lib或.dll)都得到自己的Doxy输出。

2009-01-14 22:52:41

我使用一个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服务器上有完整的文档，总是最新的代码。

2009-02-20 13:02:34

使用doxygen记录代码的最佳技巧?

推荐文章

标签

最新文章