如何标记@ref引用的结尾？

Question

I'm using Doxygen to document C++ code, and am writing a substantial amount of Doxygen doc for the code. In one place I'm making a list of groups in the code, and would like it to appear as follows:

• Control Module : the module that controls everything
• Slave Module : the module that is the slave of the Control Module

My documentation source looks like this:

- @ref CM: the module that controls everything
- @ref SM: the module that is the slave of the @CM

But, problem: Doxygen seems to be reading the reference name as CM: , not CM , and thus can't find the reference. So, somehow I need to tell Doxygen where the reference name ends. (For example, if I were using Bash, and wanted to echo a variable string with an "s" as a suffix, I'd use echo "${NOUN}s" .)

As a workaround, I could add a space between the name and the subsequent colon, but that makes the resulting doc harder to read and I'd like to avoid it.

Under Special Commands , the Doxygen manual includes the following hopeful-sounding information:

Some commands have one or more arguments. Each argument has a certain range:

• If <sharp> braces are used the argument is a single word.
• If (round) braces are used the argument extends until the end of the line on which the command was found.
• If {curly} braces are used the argument extends until the next paragraph. Paragraphs are delimited by a blank line or by a section indicator.

OK, that's all fine and good, but the documentation doesn't say, and I can't figure out, where those braces are supposed to go. Around the argument alone? Around the entire command and argument? Neither works, and I can't come up with an alternative that does work.

So, how do I indicate the end of a reference name to Doxygen? And if braces are the answer, where do they go?

Answer 1

This works for Doxygen version 1.8.11:

\ref name "":

Apparently, the empty string triggers a fall-back to use the name argument before it.

Answer 2

The Doxygen documentation you quote is describing the syntax of the Doxygen documentation, not of sources to be parsed by your use of Doxygen.

In other words, if <sharp> braces are used when describing a command, it takes a single word; and so on.

Looking at the documentation of @ref :

 \\ref <name> ["(text)"] 

The name argument is in "sharp braces," and so it's just a single word. Unfortunately, Doxygen seems to interpret : as part of that word. Your best bet would be to introduce a space:

@ref CM : the ...

You could also try whether a zero-width character would break the word recognition:

@ref CM‌: the ...