Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to escape special commands in Doxygen inline code

Tags:

c++

c

doxygen

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

like image 677
riot_starter Avatar asked May 02 '14 14:05

riot_starter


People also ask

How do I use Doxygen?

There are two main steps in using Doxygen: 1. To use Doxygen, you write comments in code using the format that Doxygen understands. The comments are included in the header files (.h) files. But, you should still comment code in your .cpp files, though Doxygen won’t use them extensively.

What is a Doxygen alias?

Doxygen provides a large number of special commands, XML commands, and HTML commands. that can be used to enhance or structure the documentation inside a comment block. If you for some reason have a need to define new commands you can do so by means of an alias definition.

What is the HTML documentation generated by Doxygen?

Click here for the corresponding HTML documentation that is generated by doxygen. Indicates that a comment block contains documentation for a group of classes, files or namespaces. This can be used to categorize classes, files or namespaces, and document those categories.

Why is my call graph not being generated by Doxygen?

When this command is put in a comment block of a function or method and then doxygen will not generate a call graph for that function. The call graph will not be generated regardless of the value of CALL_GRAPH. The completeness (and correctness) of the call graph depends on the doxygen code parser which is not perfect.


2 Answers

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

Use \c \#define for something..
like image 109
πάντα ῥεῖ Avatar answered Oct 23 '22 01:10

πάντα ῥεῖ


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.

like image 26
David Hammen Avatar answered Oct 23 '22 01:10

David Hammen