3

我正在尝试使用 doxygen 来记录我的单元测试，但我想在代码中而不是在测试标头中记录它们，以减少进行类似测试时的复制/粘贴错误。值得注意的是，我使用的是 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()

{注意这里没有步骤}

功能描述输出：

无效 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 ......这是我最终真正想要的......}

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

4

3 回答 3

0

我很同情你的困境，但据我所知，Doxygen 真的只是用来记录特定的代码对象（文件、类、命名空间、变量等），而不是任意的代码行。

目前，我能想到的规避这个缺点的唯一可能性是生成包含您想要通过\codecommand记录的实际代码的注释。

我可以想到两种方法来实现这一点：

  1. 在 Doxy 注释中放置某种特殊的字符串（例如，DOXY_INLINE_CODE），它应该与单行代码相关联。然后编写一个过滤器（请参阅FILTER_PATTERNS\code <nextline> \endcode ），用过滤器看到<nextline>的下一行代码替换这个字符串。我不确定 Doxygen 会将这些评论放在哪里或它们的外观；不幸的是，它们可能非常丑陋。（我不喜欢的一个奇怪行为是该\code命令似乎去掉了前导空格，所以你不会让缩进正常工作。）
  2. 编写一个“Doxygen runner”，.dox在调用doxygen. 这些自动生成的.dox文件将包含从相应.cpp或其他源文件生成的文档。您可以使用各种 Doxygen 命令链接回实际源代码的文档，也可以在源代码文档中插入文档的副本.dox（反之亦然）。

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

于 2014-07-23T16:39:48.787 回答
0

我记得在寻找类似解决方案时遇到过这个问题。我想尽可能地记录用户测试过程，使其尽可能接近他们相应的单元测试或单元测试组。以下是我们使用 Doxygen 组/子组实现的解决方案的一个子集。

定义了一个单独的manual-test.dox文件来创建一个顶级组和几个子组，在这些子组下收集特定的手动测试。

/**
@defgroup manualtest Manual Testing Instructions
@{
This section contains a collection of manual testing...

@defgroup menutest Menu Tests

@defgroup exporttest Import/Export Tests

@}
*/

下面显示了一个带有单元测试文档和手动测试说明的 Java 单元测试类的示例。

public MenuTests {
   ...

   /**
    * @addtogroup menutest
    * **Open File Test**
    * 
    * The purpose of this test is to...
    *
    * -# Do something
    * -# Verify something
    */
   /**
    * This unit test verifies that the given file can be created via
    * the File->Open... menu handler. It...
    */
   @Test
   public void open_file_test() {
      ...
   }
}

生成的 HTML 文档将包括模块部分下的手动测试说明页面。所述页面将包含如中给出的标记细节和到每个已定义子组的模块页面的链接，例如菜单测试。manual-test.dox

菜单测试页面将显示添加到此子组的所有手动单元测试步骤，从而提供一个单独的文档，可以作为软件测试计划或用户测试计划的一部分通过引用包含在内。

唯一需要注意的是，无法明确定义将测试指令添加到组中的顺序。在单个类中定义时，它们按定义顺序添加，多个类按字母顺序解析。

对于需要对如何收集测试进行更多控制的项目，Doxygen 用于创建 XML 输出。使用 XSLT 模板提取测试用例并根据需要进行排序，但这是另一个问题。

于 2017-01-27T07:11:41.290 回答
-1

使用支持从内联注释生成文档的工具：

Doxygen 有perl 的助手，这是编写 NaturalDocs 的内容。

于 2013-12-10T19:30:17.443 回答