Doxygen @return描述中使用@link导致悬浮提示文本截断问题

问题根因 #

该现象是Doxygen 1.8.16版本的注释解析bug导致：当@return这类块级注释命令后直接换行放置@link标签时，Doxygen生成给IDE做索引的XML注释文件会出现标签闭合异常，IDE读取注释做悬浮提示时会误判为注释块结束，导致内容截断。
不需要删除链接标签，通过以下任意一种方案即可同时满足「静态文档保留枚举跳转链接」「IDE悬浮提示完整展示内容」两个需求。

方案1：调整注释写法（无需改配置，兼容性最好） #

优先使用Doxygen自动链接特性（推荐） #

Doxygen默认开启自动链接能力，只要枚举类型、枚举值已经被Doxygen纳入解析范围，直接在注释里写类型/枚举值原名，不需要手动包裹@link/@endlink，生成静态文档时会自动添加跳转链接，同时完全规避标签解析bug。
修改后的头文件注释示例：

<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 THE_RESULT enumeration.
 * <TABLE>
 * <TR><TH>Result</TH><TH>Description</TH></TR>
 * <TR><TD>SUCCESS</TD><TD>The method ran perfectly.</TD></TR>
 * <TR><TD>ERROR1</TD><TD>The method didn't run so well.</TD></TR>
 * <TR><TD>ERROR2</TD><TD>The method utterly failed.</TD></TR>
 * </TABLE>
 *
 * @see MyOtherFunction
 * @ingroup These_Methods
 */
THE_METHOD THE_RESULT MyCoolFunction();

对应的调用示例代码不需要做任何修改：

<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!
    }
}

若需保留显式@link标签 #

如果需要自定义链接显示文本、必须显式写@link，不要在@return命令后换行写内容，把@return和首行描述放在同一行即可，示例：

* @return The @link THE_RESULT @endlink enumeration.
* <TABLE>
* // 后续表格内容保持不变

方案2：修改Doxygen配置（无需改动现有注释） #

如果已有大量存量注释不想逐一修改，调整Doxyfile配置文件的两个参数即可：

• 确认AUTOLINK_SUPPORT = YES：该选项为默认开启项，开启后未手动加@link的枚举、类型、函数名会自动生成跳转链接，和手动加标签的静态文档效果完全一致
• 设置XML_NS_MEMB_FILE_SCOPE = YES：该配置会修正v1.8.16版本生成IDE索引XML时的标签闭合bug，解决IDE解析注释截断的问题

修改配置后重新生成文档即可生效。

注意事项 #

• 尽量不要在@return、@param、@note这类块级注释命令后直接换行放置@link、@image这类独立标签，旧版本Doxygen很容易出现XML生成异常
• 对于全局可见、已经被Doxygen解析的类型、枚举、函数，优先使用自动链接能力，既减少注释书写工作量，也能规避大部分跨工具的注释兼容问题

内容的提问来源于stack exchange，提问作者rottlover