unit-testing - 根据代码记录单元测试

Question

我正在尝试使用 doxygen 来记录我的单元测试，但我想将它们与代码一起记录，而不是在测试 header 中，以减少进行类似测试时的复制/粘贴错误。值得注意的是，我使用的是 RTF 输出格式。

    /** @brief A method for testing doxygen method documentation
     * @test
     *     -#Step 1
     *     -#Step 2
     *     -#Step 3
     */
    [TestMethod()]
    public void DoxygenScratchPadInHeader()
    {
        // code that may or may not be in sync with header
    }

    /** @brief A method for testing doxygen method documentation
     * @test
     */
    [TestMethod()]
    public void DoxygenScratchPadInLine()
    {
        /// @par
        ///     -#  Initialize the value to 0
        int i = 0;

        /// @par
        ///     -# Add a number
        i += 3;

        /// @par
        ///     -# Assert that the number is three
        Assert.AreEqual(3, i);
    }

测试列表输出:

成员UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader()

1. 第 1 步
2. 第 2 步
3. 第 3 步

成员UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine()

{注意此处没有步骤}

函数描述输出:

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader ()

一种测试 doxygen 方法文档的方法。测试:

1. 第 1 步
2. 第 2 步
3. 第 3 步

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine ()

一种测试 doxygen 方法文档的方法。测试:

1.  Initialize the value to 0


1.  Add a number


1.  Assert that the number is three 

{将最后一位显示为代码，因为 stackoverflow 正在将重复的 1. 纠正为 1. 2. 3...这才是我最终真正想要的...}

对于实现内联测试步骤文档有更好的想法吗？我不太关心测试列表中没有出现的步骤，我们可以只接受对函数的引用。

Answer 1

我非常同情您的困境，但据我所知，Doxygen 实际上只是设计用于记录特定的代码对象(文件、类、命名空间、变量等)，而不是而不是任意的代码行。

目前，我能想到的规避此缺点的唯一可能性是生成注释，其中包含您想要通过 \code command 记录的实际代码。 .

我可以想到两种方法来实现这一目标:

1. 在 Doxy 注释中放入某种特殊字符串(例如 DOXY_INLINE_CODE )，该字符串应与单行代码关联。然后编写一个过滤器(请参阅 FILTER_PATTERNS )以将此字符串替换为 \code <nextline> \endcode哪里<nextline>是过滤器看到的下一行代码。我不确定 Doxygen 会将这些注释放在哪里或者它们看起来如何；不幸的是，它们可能非常丑陋。 (我不喜欢的一个奇怪的行为是 \code 命令似乎会去除前导空格，因此您无法让缩进正常工作。)
2. 编写一个“Doxygen 运行程序”，它会自动生成 .dox在调用 doxygen 之前从代码中获取文件。这些自动生成的.dox文件将包含从相应的 .cpp 生成的文档或其他源文件。您可以使用各种 Doxygen 命令来 link back to实际源代码的文档，您也可以 insert a copy .dox的源代码文档中的文档(反之亦然)。

这些都是 hack，您必须花很多时间来摆弄 Doxygen 才能让它很好地处理这种情况，但我希望这些建议有所帮助。祝你好运。 (我目前正在做类似的事情，让 Doxygen 很好地记录 Google 测试，也是在一个高度监管行业的项目背景下进行的。)