How to embed the body of a live unit test function as example usage with Doxygen?

I want to embed the body of a live unit test function as the example.

This is a similar question

In doxygen, we can show example usage:

• with an entire .c file using the @example instruction.


• with a snipper using the @code instruction


• somehow with the @snippet directive + EXAMPLE_PATH (can't get it to work)

@example won't work because I don't have just one unit test per c file. My test files have a bunch of unit tests in them organized as functions.

@code means I have to write some code that isn't going to get compiled or actually executed. (In Python, there are doctests -- which is the reverse of what I'm looking for because doctests can be actually executed as a unit test. Something like that would be fine here.)

@snippet might work. It looks like we would decorate the unit test and that makes it into a snippet. I can't get this to work. (see below)

Here's an example:

/**
 * @brief Sets the values to zero
 *
 */
void set_to_zero(my_type_t *t)
{
    t->x = 0;
    t->y = 0;
}

... in another test_suite_1.c file, where I have lots of unit tests. Here's one ...

int test_set_to_zero()
{
    my_type_t t;
    set_to_zero(t);
    MYASSERT(t.x == 0);
    MYASSERT(t.y == 0);
}

I would like just this unit test, from my test_suite_1.c file (not all unit tests in the whole file) to appear in the documentation as example usage of this particular function.

The reason I want to do this is so that I can keep practicing DRY. The unit test is essentially a pretty good example of basic usage.

Is there some directive like: @embed_function_body_here<test_set_to_zero>

Going back to @snippet. As I said, it didn't work. Here's what I tried to do with the @snippet directive:

My unit tests are in a \test folder. There are separate .c files containing unit tests (e.g. test_suite_1.c, test_suite_2.c, etc

... in test_suite_1.c ...

//! [Zero Test]
int test_set_to_zero()
{
    my_type_t t;
    set_to_zero(t);
    MYASSERT(t.x == 0);
    MYASSERT(t.y == 0);
}
//! [Zero Test]

... in regular_code.c ...

/**
 * @brief Sets the values to zero
 * @snippet test\test_suite_1.c Zero Test
 *
 */
void set_to_zero(my_type_t *t)
{
    t->x = 0;
    t->y = 0;
}

... in doxyfile ...

...
EXAMPLE_PATH = test
EXAMPLE_RECURSIVE = YES
...

This whole @snippet endeavor doesn't work. Nothing shows in the resulting html where the snippet should be.