命名空间内模板类的Doxygen成员引用解析问题问询

在命名空间template_test内定义模板类TemplateClass时，成员函数的文档注释中使用\ref短引用其他成员会解析失败：

/// @brief 我的命名空间
namespace template_test
{

template <int param_v>
class TemplateClass
{
  public:
    /// @brief \ref template_test::TemplateClass::func2()    <- 正常解析
    int func1() { return 1; }

    /// @brief \ref func1()                                  <- 解析失败
    int func2() { return 2; }
};

class InstanceClass
{
    TemplateClass<5> m_templ_class;
};

} // namespace template_test

此时会触发错误：unable to resolve reference to 'func1()' for \ref command。使用包含命名空间的全限定签名引用可以解决问题，但会提升重构成本。

观察到的特殊现象 #

1. 模板类位于全局命名空间时，短引用可正常解析：

template <int param_v>
class TemplateClass
{
  public:
    /// @brief \ref func2()       <- 正常解析
    int func1() { return 1; }

    /// @brief \ref func1()       <- 正常解析
    int func2() { return 2; }
};

/// @brief 我的命名空间
namespace template_test
{

class InstanceClass
{
    TemplateClass<5> m_templ_class;
};

} // namespace template_test

2. 非模板类中，短引用可正常解析：

/// @brief 我的命名空间
namespace test
{

class NoTemplateClass
{
  public:
    /// @brief \ref func2()       <- 正常解析
    int func1() { return 1; }

    /// @brief \ref func1()       <- 正常解析
    int func2() { return 2; }
};

class InstanceClass
{
    NoTemplateClass m_no_templ_class;
};

} // namespace test

额外发现 #

移除InstanceClass的定义后，TemplateClass内的短引用可以正常生成链接。

当前Doxygen配置差异（与1.9.5默认配置对比） #

# Difference with default Doxyfile 1.9.5 (2f6875a5ca481a69a6f32650c77a667f87d25e88)
PROJECT_NAME           = ${PROJECT_NAME}
OUTPUT_DIRECTORY       = ${DOCS_OUTPUT_DIRECTORY}
STRIP_FROM_PATH        = ${PROJECT_SOURCE_DIR}
TOC_INCLUDE_HEADINGS   = 0
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
CASE_SENSE_NAMES       = YES
SORT_MEMBER_DOCS       = NO
WARN_AS_ERROR          = YES
WARN_LOGFILE           = ${DOXYGEN_WARN_LOG_FILE}
INPUT                  = ${INPUTS}
FILE_PATTERNS          = ${FILE_PATTERNS}
RECURSIVE              = YES
EXCLUDE_PATTERNS       = *.txt
EXAMPLE_RECURSIVE      = YES
HTML_OUTPUT            = _doxygen
HTML_EXTRA_STYLESHEET  = ${SOURCE_DIR}/tools/doxygen/doxygen-awesome.css
USE_MATHJAX            = YES
MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
MATHJAX_EXTENSIONS     = TeX/AMSmath \
                         TeX/AMSsymbols
SEARCHENGINE           = NO
GENERATE_LATEX         = NO
LATEX_CMD_NAME         = latex
XML_OUTPUT             = _doxygen/xml
MACRO_EXPANSION        = YES
PREDEFINED             = TSM_USE_VFC_UNITS
DIRECTORY_GRAPH        = NO
DOT_IMAGE_FORMAT       = svg
INTERACTIVE_SVG        = YES
DOTFILE_DIRS           = .
PLANTUML_JAR_PATH      = /usr/share/plantuml/plantuml.jar
DOT_GRAPH_MAX_NODES    = 350

疑问 #

1. 上述特殊行为的成因是什么？
2. 是否存在比指定全限定名更简便的引用方式？

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