Documenting Unit Tests in line with code

Question

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);
    }

Test List Output:

Member UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader ()

1. Step 1
2. Step 2
3. Step 3

Member UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInLine ()

{note no steps here}

Function description output:

void UpdateProtocolQATests.CUpdateProtocolTest.DoxygenScratchPadInHeader ()

A method for testing doxygen method documentation. Test:

1. Step 1
2. Step 2
3. Step 3

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 

{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.

Answer 1

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.

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. 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).

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.)