1

I am trying to document my C code using doxygen. I have some default values set as macros with #define. (I know C does not have default values but this is just an example)

e.g.:

#define DEFAULT_WIDTH  100
#define DEFAULT_HEIGHT 200

Inside doxygen I have added an alias that handles default values in the way I want. Consider the example function below

//! Initializes something
//! @param width The width @default DEFAULT_WIDTH
//! @param height The height @default DEFAULT_HEIGHT
//! @return Result of initialization
char initSomething(int width,int height);

This will generate the documentation as I want it except one important fact. DEFAULT_WIDTH and DEFAULT_HEIGHT do not get expanded , I get the macro names and not 100 and 200 respectively. I do have MACRO_EXPANSION and ENABLE_PREPROCESSING checked on.

What am I missing? Is there actually any way to achieve this using doxygen?

I am configuring doxygen with doxywizard and I am currently testing under Windows.

EDIT: As ugoren points out it is possible to just document the macro and then doxygen will link that documentation to them. This is how my current implementation is in my project actually. But I am trying to consider additional options - if any exist.

Lefteris
  • 3,196
  • 5
  • 31
  • 52

2 Answers2

2

I don't think there's anything stronger than MACRO_EXPANSION and ENABLE_PREPROCESSING.
The problem is probably that macros in comments are normally not expanded. There's a good reason for it - imagine the macro max expanded inside the documentation.

You can document the macro, so readers of the documentation would be able to find the real value easily.

ugoren
  • 16,023
  • 3
  • 35
  • 65
  • Yes just documenting the macro is a possible solution and this is what I am currently doing but I am wondering if there is any way possible to do it otherwise. Thanks for the input – Lefteris Feb 15 '12 at 19:32
  • sure macros can be expanded inside the doxygen documentation – Jens Gustedt Feb 15 '12 at 21:52
2

Add something like

EXPAND_AS_DEFINED += DEFAULT_WIDTH

to your doxygen configuration file.

(The documentation of P99 is full of such macro expansions. Its doxygen configuration file should come with the distribution.)

Jens Gustedt
  • 76,821
  • 6
  • 102
  • 177
  • Hello Jens, thanks for the input. I had tried EXPAND_AS_DEFINED before making the question but it did not work. If you say though that it has worked for P99 then well , I must be at fault or it could be some peculiarity of doxywizard. I have checked P99 in the past since I have even commented in your blog about it and I will go compare the configuration file generated by doxywizard with your configuration file. – Lefteris Feb 16 '12 at 05:10
  • It still does not work I am afraid. But I notice one thing in your configuration file that differs from mine. Why in the main conf file there is only one EXPAND_AS_DEFINED += FOOTNOTE and all the other seem to be in a different file included by the main doxygen conf file? I am just adding a bunch of EXPAND_AS_DEFINED += MACRO in my conf file and nothing happens. Could there be any difference as to that? All the other flags concerning the preprocessor are set the same as P99 – Lefteris Feb 16 '12 at 05:54
  • No, I don't think that having them in include files or not should make a difference. In P99 this is just to modularize better. The included file basically has a large list of `EXPAND_AS_DEFINED` such that this file can be included in other projects, too. There must be something fishy going on, overwriting a doxygen variable later in the config file, doxygen bailing out on your code somewhere... – Jens Gustedt Feb 16 '12 at 07:59