Search code examples
doxygen

Using @link in a @return description truncates text

I've hit a snag with Doxygen (v1.8.16) and am hoping someone can help. The function I'm documenting returns an enum that's described elsewhere, so I want to link to it in the generated documentation. All is fine and dandy on that front.

<myheader.h>
/* ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ MyCoolFunction() ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ */
/**
 * @brief This function does lots of cool stuff. You should check it out.
 *
 * Here's another line of text describing what a great function this is.
 *
 * @since 2.1.1
 *
 * @return
 * The @link THE_RESULT @endlink enumeration.
 * <TABLE>
 * <TR><TH>Result</TH><TH>Description</TH></TR>
 * <TR><TD>@link SUCCESS @endlink</TD><TD>The method ran perfectly.</TD></TR>
 * <TR><TD>@link ERROR1 @endlink</TD><TD>The method didn't run so well.</TD></TR>
 * <TR><TD>@link ERROR2 @endlink</TD><TD>The method utterly failed.</TD></TR>
 * </TABLE>
 *
 * @see MyOtherFunction
 * @ingroup These_Methods
 */
THE_METHOD THE_RESULT MyCoolFunction();

And here's an example of calling my function:

<mylittleapp.cpp>

/**

 * @file mylittleapp.cpp
 * @brief Here's an example of how to use MyCoolFunction.
 */
void Example()
{
    if (MyCoolFunction() == SUCCESS)
    {
        // Now we get to do more cool stuff
    }
    else
    {
        // Uh oh!
    }
}

The problem is for the SDK user when they want the context documentation popping up about how to use the function in their code. When I mouse-over MyCoolFunction in mylittleapp.cpp, this is what I see when the @link is in the @return.

enter image description here

Removing the @link...@endlink in the @return line fixes that problem, but then there's no link to my THE_RESULT enum in the generated documentation. How can I get the full return statement to show up in the context pop-up and also include a link in the generated doc?

Solution

  • Looks like @link ... @endlink isn't correct for internal links. Changing them to @refs fixes both problems.