Doxygen to emulate Tempate

Question

I am trying to create documentation using Doxygen to emulate C templates without much success. I hope someone knows how to do macro cheating in the doxygen preprocessor? I already tried turning on "MACRO_EXPANSION" without any luck.

EDIT: The most denatured form of this question would be: "How can I get Doxygen to process the #include preprocessor directive in the same way that the C preprocessor does?"

I have the following code in the "test" folder (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 configuration 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 template versions of the sum * function are missing from the doxygen documentation (.h or .c); for example, test.h below (although I would also be happy if it appeared in test_template.h instead):

Any thoughts?

Answer 1

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

If you do not know what the effect of doxygen preprocessing will be, you can run doxygen as follows:

doxygen -d preprocessor

This will instruct doxygen to reset the source to the standard output after preprocessing (hint: set QUIET = YES and WARNINGS = NO in the configuration file to disable any other output).

Compare this with the output obtained from the real pre-pre processor to make sure that the doxygen extension really matches what the C compiler sees.

You may need to configure configuration options related to doxygen pre-processing in order to make this work.

This, as they say, and as others commented, I would not use the C pre handler, as it is personally, but I agree that this is a matter of personal opinion.

A possible problem that comes into play: the C pre processor can generate code when expanding macros, but it will not generate comments, and all the doxigenic markup is built into the C comment.

Of course, doxygen may raise that there is a function called sum_uint8_t, but in order to really add documentation about this function, the source code will have to explicitly add “structure commands” to the source code.

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