Doxygen comment inside a macro

Question

My problem is the following : I have a set of files with the same parameters for constructors. I defined the parameters of a constructor inside a macro which is used in each file. For example, the following constructor :

Planar(BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3);

uses the BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3 macro which expand the parameters of the Planar constructor :

#define BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3                                \
  size_t height,                                                            \
  size_t width,                                                             \
  size_t stride,                                                            \
  size_t effectiveChannels,                                                 \
  BSPF_UTILS::bspf_8u* buffer

My problem is the following : I want to have the same Doxygen documentation for all constructors which uses the same macro, in other words, I want to write just one time the documentation for constructors who shared the same macro).

How can I do this ?

I tried to write a macro (with the name of the constructor for parameter) but it doesn't works since Doxygen expands the macro without line break.

Is there a good manner to do this ?

Thanks for your answers.

score 2 · Accepted Answer · answered May 31 '11 at 19:28

2

Macros are always expanded without a line break, this got nothing to do with doxygen. However, a solution is relativly simple:

Have an extra text-file ("BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3.txt" or similar) that contains the comment specific to that define, an extra

#define BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3_INCLUDE \ 
    "BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3.txt"

and finally use it in the following fashion:

// your .cpp
#include BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3_INCLUDE
Planaer::Planar(BSPF_IMAGE_FORMAT_STD_CONST_PARAMS_3){
}

The include with simply copy and paste the content of the .txt into your .cpp, and that's it.

answered May 31 '11 at 19:28

Xeo

129,499
52
291
397

Thanks for your answer, that's not a bad idea ! About the preprocessor, I was talking about the Doxygen preprocessor which expand multi-line macros on a single line. – benlaug May 31 '11 at 19:36
There is no such thing as a multi-line macro. That is why when you write what looks like a multi-line macro to you you have to put a backslash right at the end of the line. That backslash essentially tells the preprocessor that the end of line that follows isn't really an EOL. Its a space. – David Hammen May 31 '11 at 19:50
On second thought, it's not even a space. The preprocessor just eats it as if it didn't exist at all. You can test this yourself. Place the following C++-style comment before a critical piece of your code: // Comment out the next line of code \ – David Hammen May 31 '11 at 19:54

Doxygen comment inside a macro

1 Answers1