How can I include '<' in Doxygen comments?

Question

Say I'm documenting a member function using DOxygen/Visual studio compatible comments, how can I use the less than '<' symbol without creating a compiler warning but still maintaining readability in the codebase?

For example, if I did this:

    /// <summary>
    /// Verifies x < y
    /// </summary>
    bool VerifyIsLessThan(float x, float y);

The compiler says:

1>c:\MyProject\VerificationLib.h(246) : warning C4635: XML document comment applied to 'VerificationLib.VerifyIsLessThan(System.Single,System.Single)': badly-formed XML: Whitespace is not allowed at this location.

Is there any way to escape this in a way which leaves it still readable in the codebase as well as in the Doxygen generated docs?

[Edit]

I'm starting to think this is more to do with the visual studio side of things rather than Doxygen. We're using a form which should work for both. The warnings mentioned in the original question are from visual studio not Doxygen.

Digging a little deeper it looks like verbatim isn't supported directly?

score 8 · Accepted Answer · edited Mar 24 '19 at 17:28

8

just use \< and that should be it. http://www.doxygen.nl/manual/commands.html#cmdlt

edited Mar 24 '19 at 17:28

albert

8,285
3
19
32

answered Sep 14 '12 at 14:00

risingDarkness

698
12
25

1

Is there any way to do it without making it less readable? In this simple case, it's not too bad, but if (say) you had it as part of an equation, the slashes would look like divide signs... – Jon Cage Sep 14 '12 at 14:03
1

the alternative to the \ is to use @ instead. this doesn't look much better but can't be confused with a divide sign that easy. – risingDarkness Sep 14 '12 at 14:07
2

theres [formulas in doxygen](http://www.stack.nl/~dimitri/doxygen/formulas.html). i never used them but it looks like it still needs escaping of <. – risingDarkness Sep 14 '12 at 14:15
2

I think you're right about the formula for DOxygen, but I can't find any way to make the MS XML documentation understand a '<' character even if I escape it with a `\` or a `@` symbol. The only thing which comes close is `<` but that looks horrible in the codebase. – Jon Cage Sep 14 '12 at 14:58

score 3 · Answer 2 · edited Mar 24 '19 at 18:12

3

You can use code or verbatim.

edited Mar 24 '19 at 18:12

albert

8,285
3
19
32

answered Sep 14 '12 at 14:26

gammay

5,957
7
32
51

...but that has to be a whole block rather than inline with a `

` block right? i.e. `///
Make sure x is < y
` doesn't work... – Jon Cage Sep 14 '12 at 14:40

score 2 · Answer 3 · answered Sep 14 '12 at 15:00

2

The only thing I can find which allows a < character to be put inline in a summary seems to be < but it still looks ugly in the actual codebase even if intellisense and doxygen look fine...

answered Sep 14 '12 at 15:00

Jon Cage

36,366
38
137
215

score 0 · Answer 4 · edited May 23 '17 at 12:10

0

You can also put your comments inside a CDATA block, like so:

<![CDATA[ Verifies x < y ]]>

I don't know if you'd really consider that easier to read, but it helps avoid the problem Jon Cage noted, where \ might be misconstrued as a division symbol, or whatever else.

Additional information:

What does <![CDATA[]]> in XML mean?

http://forums.asp.net/t/1007641.aspx/1

edited May 23 '17 at 12:10

Community

1
1

answered Aug 21 '13 at 14:56

Travis

1,044
1
17
36

Does anyone have a complete example on how to use `CDATA` in a Doxygen block? The above example [doesn't work for me](https://stackoverflow.com/q/75837613/6271889) – Leonardo Mar 27 '23 at 16:30

How can I include '<' in Doxygen comments?

4 Answers4

Linked