How to escape special commands in Doxygen inline code

Question

I want to use inline code in a Doxygen comment:

Use `#define` for something..

Which produces the following warning:

warning: explicit link request to 'define' could not be resolved

How can I escape the # sign in order to omit this warning?

If I use the backslash (\) like this:

Use `\#define` for something..

I still get the same warning..

@LightnessRacesinOrbit - This is an undocumented misfeature. riot_starter explicitly mentioned that the backslash escape doesn't work in code spans delimited by backticks. — David Hammen, Apr 20 '16 at 16:22
@DavidHammen: πάντα ῥεῖ's answer, posted two years ago, shows the _documented_ solution. — Lightness Races in Orbit, Apr 20 '16 at 16:41
@LightnessRacesinOrbit - I thoroughly disagree. That is one way to do it. However, there is no mention in the doxygen documentation of the interactions between code spans delimited with backticks and the doxygen proper. In particular, there is no mention that doxygen's special characters cannot be escaped in a markdown code span. That is a bug as far as I'm concerned. — David Hammen, Apr 20 '16 at 17:16
@DavidHammen: Feel free to write your own answer. Personally I put this to bed two years ago. — Lightness Races in Orbit, Apr 20 '16 at 17:38
@LightnessRacesinOrbit - I **did** write my own answer. I came across this question because I received the same message, but with regard to wanting to see `"#foo bar ..."` expressed in a monospaced font in the generated documentation, including the quotes. — David Hammen, Apr 20 '16 at 17:41
@LightnessRacesinOrbit - Even Dimitri thinks this is a bug: https://bugzilla.gnome.org/show_bug.cgi?id=694425 . Also see https://bugzilla.gnome.org/show_bug.cgi?id=722062 and https://bugzilla.gnome.org/show_bug.cgi?id=760922 . — David Hammen, Apr 20 '16 at 18:07
@DavidHammen: As I said, I was done with this two years ago. Feel free to add that detail to your answer. — Lightness Races in Orbit, Apr 20 '16 at 23:49

score 16 · Answer 1 · answered Apr 20 '16 at 17:09

I ran across a similar warning but in a slightly different context. I wanted to see "#include foo" (quoted and in a monospaced font) rather that #define in the generated documentation.

What doesn't work

That doxygen supports markdown suggests that simply writing `"#include foo"` in the code should do the trick. It doesn't; there's some undocumented interaction between doxygen-flavored markdown and the rest of doxygen. Doxygen tries to process that #include as a refering to some entity named include. Writing `"\#include foo"` doesn't work, either. Doxygen proper does not see the backslash as escaping the pound symbol when used in markdown code span.

Be very careful using `stuff` in doxygen. If stuff is simple, you'll be okay, but you're better off using something else if it contains any special doxygen characters.

What does work

If you want to see

Word #foo more words.
(i.e., #foo is not in a monospaced font). Simply escape the hash symbol in the doxygen commentary:
```
/*! 
  Word \#foo more words.
 */
```
Word #foo more words.
(i.e., #foo is in a monospaced font). Use \c in conjunction with \#:
```
/*! 
  Word \c \#foo more words.
 */
```
Word #foo bar more words.
(i.e., #foo along with bar is in a monospaced font, and are not double quoted). Use <tt> in conjunction with \#:
```
/*! 
  Word <tt>\#foo bar</tt> more words.
 */
```
Word "#foo bar" more words.
(i.e., #foo along with bar are in a monospaced font, along with the double quotes that surround #foo bar). Use \c and **do not* backslash escape the hash symbol:
```
/*! 
  Word \c "#foo bar" more words.
 */
```

The last one was tricky. The character " is a special character in doxygen. The \c command operates on the string "#foo bar", and that string is not interpolated.

score 10 · Accepted Answer · edited Mar 24 '19 at 17:29

10

You probably want to use doxygen's \c and \# special commands to provide code formatting for the next word:

Use \c \#define for something..

edited Mar 24 '19 at 17:29

albert

8,285
3
19
32

answered May 02 '14 at 14:19

πάντα ῥεῖ

1
13
116
190

Tried adding [`\#`](http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmdhash) also? – πάντα ῥεῖ May 02 '14 at 16:21

How to escape special commands in Doxygen inline code

2 Answers2

What doesn't work

What does work