Doxygen for C Template Emulation

Question

I am trying to generate documentation using Doxygen for emulated templates in C without much success. I am hoping someone knows how to make the macro trickery work in the doxygen preprocessor? I have already tried enabling "MACRO_EXPANSION" without luck.

EDIT: The most denatured form of this question would be: "How can I make Doxygen handle the preprocessor directive #include in a similar way that the C preprocessor does?"

I have the following code in a folder "test" (a very contrived example):

templates.h

#ifndef TEMPLATES_H_
#define TEMPLATES_H_

#define CAT(X,Y) X##_##Y
#define TEMPLATE(X,Y) CAT(X,Y)

#endif // TEMPLATES_H_

test.h

#ifndef TEST_H_
#define TEST_H_

#include "templates.h"

#ifdef TEST_T
#error "TEST_T cannot be defined prior to this compilation step"
#endif

#define TEST_T uint8_t
#include "test_template.h"
#undef TEST_T

#define TEST_T uint16_t
#include "test_template.h"
#undef TEST_T

#endif // TEST_H_

test_template.h

#ifdef TEST_T

#include "templates.h"

TEST_T TEMPLATE(sum,TEST_T)(TEST_T a, TEST_T b);

#endif // ifdef TEST_T

test.c

#include "test.h"

#ifdef TEST_T
#error "TEST_T cannot be defined prior to this compilation step"
#endif

#define TEST_T uint8_t
#include "test_template.c"
#undef TEST_T

#define TEST_T uint16_t
#include "test_template.c"
#undef TEST_T

test_template.c

#ifdef TEST_T

TEST_T TEMPLATE(sum,TEST_T)(TEST_T a, TEST_T b)
{
   return a + b;
}

#endif // ifdef TEST_T

In my doxygen config file:

test.cfg

# Doxyfile 1.8.13

PROJECT_NAME           = "Test"
OUTPUT_DIRECTORY       = "docs_test"
TAB_SIZE               = 3
OPTIMIZE_OUTPUT_FOR_C  = YES
INPUT                  = "../test"
RECURSIVE              = YES
MACRO_EXPANSION        = YES

# Temporary to extract all without tags
EXTRACT_ALL            = YES

However, the templated versions of the sum* function aren't present in doxygen (.h or .c documentation); for example, test.h is below (although I would also be happy if it showed up in test_template.h instead):

Any thoughts?

Sidenote: Make sure you have trailing newlines on files when doing macro trickery. — user694733
Valuable note. I personally always have a newline out of habit (learned trait from systems long passed) but it won't show in the code snippets above. — Squirrel

Marc Alff Marc Alff · Accepted Answer · 2017-02-28T07:54:25

From the doxygen documentation: http://www.doxygen.nl/manual/preprocessing.html

If you are unsure what the effect of doxygen's preprocessing will be you can run doxygen as follows:

doxygen -d Preprocessor

This will instruct doxygen to dump the input sources to standard output after preprocessing has been done (Hint: set QUIET = YES and WARNINGS = NO in the configuration file to disable any other output).

Compare this to the output generated from the real c pre processor, to make sure what doxygen expands actually matches what the C compiler sees.

You may need to tweak the configuration variables related to pre processing in doxygen to make this work.

That being said, and as others have commented, I would not use the C pre processor like this personally, but I agree this is a matter of personal opinion.

A possible issue that comes into play: the C pre processor can generate code while expanding macros, but it will not generate comments, and all the doxygen markup is embedded in C comments.

Sure, doxygen might pick up that there is a function named sum_uint8_t, but to really add documentation about this function, the source code will need to explicitly add 'structural commands' in the source code.

See http://www.doxygen.nl/manua/docblocks.html#structuralcommands

Doxygen for C Template Emulation

1 Answers