我想弄清楚是否有一种方法可以使用 Doxygen 创建自定义标签。我确实找到了 ALIAS 配置文件选项,但这并不完全符合我的需要。基本上在我的代码中,我希望能够编写类似的东西
/// \req Requirement #322 - blah blah
然后让 Doxygen 像它一样为具有此自定义标记的行创建一个列表\bug
和\todo
命令。Doxygen 可以吗?
我想弄清楚是否有一种方法可以使用 Doxygen 创建自定义标签。我确实找到了 ALIAS 配置文件选项,但这并不完全符合我的需要。基本上在我的代码中,我希望能够编写类似的东西
/// \req Requirement #322 - blah blah
然后让 Doxygen 像它一样为具有此自定义标记的行创建一个列表\bug
和\todo
命令。Doxygen 可以吗?
\bug
和的推广\todo
是\xrefitem
。
我建议的解决方案是:
在 Doxyfile 中:
ALIASES += "req=\xrefitem req \"Requirement\" \"Requirements\" "
在记录的代码中:
/// \req #42 - The system shall work in any situation
谢谢莫维希尔!我已采用您的解决方案并为我的目的对其进行了扩展。
下面的文本进入我的 Doxyfile:
ALIASES += req{1}="\ref SRTX_\1 \"SRTX-\1\" "
ALIASES += satisfy{1}="\xrefitem satisfy \"Satisfies requirement\" \"Requirement Implementation\" \1"
ALIASES += verify{1}="\xrefitem verify \"Verifies requirement\" \"Requirement Verification\" \1"
其中 SRTX 是我的项目的名称,用作需求的前缀。
然后,我创建了一个名为 Requirements.dox 的文件,该文件在我的需求管理工具(在我的例子中是问题跟踪器)中提供了需求 ID 和需求 URL 之间的链接。
/**
@page Requirements
@section Build1
@anchor SRTX_1113
<a href="https://foo.bar.com/mantis/view.php?id=1113">SRTX-1113</a>
@anchor SRTX_1114
<a href="https://foo.bar.com/mantis/view.php?id=1114">SRTX-1114</a>
*/
如果您不需要链接到外部源,也可以将需求文本放在锚标记中。
在我的代码中,我有:
/**
* This is the basic executive that schedules processes.
* @satisfy{@req{1114}}
*/
class Scheduler: public Process
{
...
}
在我的测试中,我提出:
/**
* Provide a number of tests for process scheduling.
* @verify{@req{1114}}
*/
class Scheduler_ut : public CppUnit::TestFixture
{
...
}
这为我提供了需求、需求实施和需求验证的相关页面。它还在类描述(或功能——无论您放置标签的位置)中提供满足需求和验证需求部分。
结合上面的两个答案,您可以拥有一个干净的需求标签,该标签将构建一个交叉引用表,并且还可以在您的文档中提供到需求 repo 的直接链接:
Doxygen 配置文件:
别名 ="requirement{1}=@xrefitem requirement \"Requirements\" \"Requirements Traceability\" <a href=\"http://your.requirementtool.com/browse/\1\">\1</a>"
源代码:
@requirement{REQ-123}
Brief textual summary of this requirement item
This will render in the documentation as:
Requirements: