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

当前回答

如果您发现配置指令INLINE_SOURCES在文档中放置了太多代码,您可以使用\snippet命令手动引用代码的特定部分。

  /**
   * Requirment XYZ is implemented by the following code.
   * 
   * \snippet file.c CODE_LABEL
   */
  int D() 
  {
     //[CODE_LABEL]
     if( A )
     {
        B= C();
     }
     //[CODE_LABEL]
  }

注意:snippet从EXAMPLE_PATH获取文件,而不是源路径。您必须将INPUT指令中的文件和路径列表放在EXAMPLE_PATH指令上。

其他回答

当我发现自己在高分辨率的屏幕上编辑代码时,我已经从使用反斜杠转向使用@前缀的Doxygen命令。不那么嘈杂的反斜杠发现自己现在太难以分辨出Doxygen命令。

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

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

使用组将代码组织成模块。

请记住,您可以将几乎所有内容放到多个组中,以便它们可以用于提供语义标记,就像Stack Overflow中的标记一样。例如,可以将内容标记为特定于给定平台的内容。

您还可以使用组来匹配IDE中的文件夹层次结构,如我的RB2Doxy示例输出所示。

组在嵌套时工作得很好——我有一个OOFILE源代码的大示例。

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

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

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

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