CODEWITHSUNDEEP
cc-preprocessordoxygen
OllieB
OllieB

Reputation: 1431

Expand pragma to a comment (for doxygen)

Comments are usually converted to a single white-space before the preprocesor is run. However, there is a compelling use case.

#pragma once   

#ifdef DOXYGEN
  #define DALT(t,f) t
#else
  #define DALT(t,f) f
#endif

#define MAP(n,a,d) \
  DALT ( COMMENT(| n | a | d |) \
       , void* mm_##n = a \
       )

/// Memory map table
/// | name | address | description |
/// |------|---------|-------------|
MAP (reg0  , 0       , foo         )
MAP (reg1  , 8       , bar         )

In this example, when the DOXYGEN flag is set, I want to generate doxygen markup from the macro. When it isn't, I want to generate the variables. In this instance, the desired behaviour is to generate comments in the macros. Any thoughts about how?

I've tried /##/ and another example with more indirection

#define COMMENT SLASH(/)
#define SLASH(s) /##s

neither work.

Upvotes: 1

Views: 578

Answers (2)

albert
albert

Reputation: 9012

In doxygen it is possible to run commands on the sources before they are fed into the doxygen kernel. In the Doxyfile there are some FILTER possibilities. In this case: INPUT_FILTER the line should read:

INPUT_FILTER = "sed -e 's%^ *MAP *(\([^,]*\),\([^,]*\),\([^)]*\))%/// | \1 | \2 | \3 |%'"

Furthermore the entire #if construct can disappear and one, probably, just needs:

#define MAP(n,a,d) void* mm_##n = a

Upvotes: 4

zwol
zwol

Reputation: 140445

The ISO C standard describes the output of the preprocessor as a stream of preprocessing tokens, not text. Comments are not preprocessing tokens; they are stripped from the input before tokenization happens. Therefore, within the standard facilities of the language, it is fundamentally impossible for preprocessing output to contain comments or anything that resembles them.

In particular, consider

#define EMPTY
#define NOT_A_COMMENT_1(text) /EMPTY/EMPTY/ text
#define NOT_A_COMMENT_2(text) / / / text
NOT_A_COMMENT_1(word word word)
NOT_A_COMMENT_2(word word word)

After translation phase 4, both the fourth and fifth lines of the above will both become the six-token sequence

[/][/][/][word][word][word]

where square brackets indicate token boundaries. There isn't any such thing as a // token, and therefore there is nothing you can do to make the preprocessor produce one.

Now, the ISO C standard doesn't specify the behavior of doxygen. However, if doxygen is reusing a preprocessor that came with someone's C compiler, the people who wrote that preprocessor probably thought textual preprocessor output should be, above all, an accurate reflection of the token sequence that the "compiler proper" would receive. That means it will forcibly insert spaces where necessary to make separate tokens remain separate. For instance, with test.c the above example,

$ gcc -E test.c
...
/ / / word word word
/ / / word word word

(I have elided some irrelevant chatter above the output we're interested in.)

If there is a way around this, you are most likely to find it in the doxygen manual. There might, for instance, be configuration options that teach it that certain macros should be understood to define symbols, and what symbols those are, and what documentation they should have.

Upvotes: 2

Related Questions