CODEWITHSUNDEEP
c++cdoxygen
riot_starter
riot_starter

Reputation: 1398

How to escape special commands in Doxygen inline code

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..

Upvotes: 14

Views: 10501

Answers (2)

πάντα ῥεῖ
πάντα ῥεῖ

Reputation: 1

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

Use \c \#define for something..

Upvotes: 10

David Hammen
David Hammen

Reputation: 33106

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.

Upvotes: 17

Related Questions