Misuse of @see in doxygen markup Topic is solved

[jwwalker]

I don't claim to be an expert in Doxygen, but I see many places where @see is used inappropriately in Ogre headers. There are 2 problems:

1. @See, capitalized, is not recognized by doxygen as markup, so you end up with an ugly @ sign in the docs.

2. If you use @see in the middle of a sentence, it breaks up the sentence, and there is generally a better way to get the linking you want.

As an example of the second case, see the documentation of HlmsUnlitDataBlock::setUseColour, which is set up like this:

Code: Select all

/// Controls whether the value in @see setColour is used.

and the output looks like

Controls whether the value in.

See also
setColour is used.

It looks much better if the markup is

Code: Select all

/// Controls whether the value in setColour() is used.

If I were to submit a pull request fixing a bunch of these issues, would it be welcome, or would it be considered more disruptive than what it's worth?

[sercero]

No answer?

[jwwalker]

By the way, that's not the only documentation markup error that I've seen in multiple places. Another is the use of an asterisk to attempt to indicate an unordered list item, which actually gets ignored in a comment block that begins /**.

[sercero]

Why don't you submit a small patch to get the attention of the developers.

[dark_sylinc]

Yeah incremental PRs would be good.

Most of the "@see" errors are from myself wrongly assuming that:

"@see myFunction"
would link to myFunction.

I later learnt the desired behavior could be achieved by writing "see ClassName::myFunction" while "@see" would actually have to be rarely used.

I wrote Colibri with the "correct" way and there are a few examples of what I mean:

• Correct use of @see (creates a separate section, simply says "for a lot more detail see this section of the manual")

• Correct use of @see (creates a separate section, simply says "for a lot more detail see this section of the manual")

• Correct use of "see Class::Func" which is only meant to make a link to Class::Func.

The best way to submit those patches is now. Because OgreNext 3.0 has already touched & messed up every file due to clang-format + C++11 adoption.

[jwwalker]

I later learnt the desired behavior could be achieved by writing "see ClassName::myFunction" while "@see" would actually have to be rarely used.

If the method is in the class being documented, you can say "see myFunction()" rather than including the class name.

[dark_sylinc]

Cool if that works it's ok.

[jwwalker]

My @see fixes have been merged as PR #284. I have several more blocks of documentation format fixes coming.