根据代码记录单元测试 [英] Documenting Unit Tests in line with code

问题描述

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

I'm trying to use doxygen to document my unit tests, but I'd like to document them in-line with the code instead of in the test header to reduce copy/paste errors when making similar tests. Of note, I'm using the RTF output format.

    /** @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（）

Member UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader ()

1. 步骤1


2. 步骤2


3. 第3步

成员UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine（）

Member UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine ()

{此处不注意任何步骤}

{note no steps here}

函数描述输出：

无效UpdateProtocolQATests。 CUpdateProtocolTest.DoxygenScratchPadInHeader（）

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader ()

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

A method for testing doxygen method documentation. Test:

1. 步骤1


2. 步骤2


3. 第3步

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine（）

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine ()

一种测试脱氧方法文档的方法。
测试：

A method for testing doxygen method documentation. Test:

1.  Initialize the value to 0


1.  Add a number


1.  Assert that the number is three 

{将最后一位显示为代码，因为stackoverflow正在将重复的1.校正为1. 2. 3 ...最后...}

{displaying last bit as code because stackoverflow is correcting the repeated 1. to 1. 2. 3... which is what I actually want in the end...}

关于实现在线测试步骤文档的更好的主意吗？我不太关心没有出现在测试列表中的步骤，我们可以只使用对函数的引用。

Any better ideas for implementing in-line test step documentation? I don't care so much about the steps not appearing in the test list, we can live with just the references to the functions.

推荐答案

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

I'm quite sympathetic to your plight, but as far as I can tell, Doxygen really is only designed to document specific code-objects (files, classes, namespaces, variables, etc) rather than arbitrary lines of code.

目前，我能想到的唯一避免这种缺点的方法是生成包含所需代码的注释通过 \code 进行记录命令。

At the moment, the only possibility I can think of for circumventing this shortcoming is to generate comments that include the actual code that you're wanting to document via the \code command.

我可以通过两种方式实现此目的：

There are two ways I can think of for accomplishing this:

1. 在Doxy注释中放入某种与单行代码相关联的特殊字符串（例如， DOXY_INLINE_CODE ）。然后编写一个过滤器（请参见 FILTER_PATTERNS ），以将该字符串替换为 \code< nextline> \endcode ，其中< nextline> 是过滤器看到的下一行代码。我不确定Doxygen将这些评论放在何处或看起来如何；不幸的是，它们可能很难看。 （我不喜欢的一个奇怪的行为是， \code 命令似乎去除了前导空格，因此您不会得到缩进以使其正常工作。）


2. 编写一个 Doxygen运行器，该代码将在调用 doxygen 之前自动从您的代码生成 .dox 文件。这些自动生成的 .dox 文件将包含从相应的 .cpp 或其他源文件生成的文档。您可以使用各种Doxygen命令来链接回实际来源的文档代码，也可以插入 > .dox 源代码文档中的文档（反之亦然）。

1. Put some sort of special string (say, for instance, DOXY_INLINE_CODE) in the Doxy comments that should be associated with a single line of code. Then write a filter (see FILTER_PATTERNS) to replace this string with \code <nextline> \endcode where <nextline> is the next line of code that the filter sees. I'm not sure where Doxygen would put these comments or how they'd look; they might be pretty ugly, unfortunately. (One odd behavior I dislike is that the \code command seems to strip leading spaces, so you wouldn't get indentation to work correctly.)
2. Write a "Doxygen runner" that would automatically generate .dox files from your code before calling doxygen. These auto-generated .dox files would contain documentation generated from corresponding .cpp or other source files. You can use various Doxygen commands to link back to the documentation of the actual source code, and you can also insert a copy of the .dox documentation in the source code documentation (or vice-versa).

这些是黑客，并且您必须花很多时间与Doxygen纠缠在一起才能使其很好地处理此案件，但我希望这些建议能有所帮助。祝你好运。 （我目前正在做类似的事情，使Doxygen能够很好地记录Google测试，而且是在针对高度管制的行业的项目中。）

These are hacks, and you'd have to fiddle around with Doxygen quite a bit to get it to handle this case nicely, but I hope these suggestions help somewhat. Best of luck. (I'm currently working on doing something similar to get Doxygen to nicely document Google Tests, also in the context of a project for a highly-regulated industry.)

这篇关于根据代码记录单元测试的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！