Doxygen 中的动态超链接引用

Question

Doxygen 能否构建引用（例如链接）只在某处定义一次，并且对它的任何引用都会获得相应的重定向？ 这将允许\see 命令指向正确的资源，而无需在代码中的任何地方复制 URL，同时在需要时可以轻松更改所述链接。

生成的文档看起来有点像这样：

ma​​inpage.md

这里定义了有用的链接

A guide to something
Datasheet of something

source.c 文件参考

(...)
另见
A guide to something //指向 mainfile.md 中定义的 URL

[编辑] 感谢 cmets 中的 @albert，我已经设法使用 \snippetdoc 做到了这一点，但是 block-id 之后的任何文本都会使 doxygen 无法呈现 sn-p。

工作示例：
知道我的链接是在 docs/mainpage.dox 文件中定义的，如下所示：

[url_to_link1]
<a href="linkToSomething">Link description</a>
[url_to_link1]

[url_to_link2]
<a href="linkToSomething">Link description</a>
[url_to_link2]

这行得通：

/**
* \file
* \section links "Useful Links"
* - \snippetdoc docs/mainpage.dox url_to_link1
* - \snippetdoc docs/mainpage.dox url_to_link2
*/

这不是：

/**
* \file
* \brief     Some function definition
* \see       API reference on specific subject (more info: \snippetdoc docs/mainpage.dox url_to_link1)
*/

Doxygen 版本是 1.8.14

Answer 1

如问题和 cmets 所示，此问题的解决方案在于命令\snippetdoc，另一种方法是定义ALIAS（在Doxyfile doxygen 配置文件中）以供参考并使用定义的命令/别名在需要的地方。

如 OP 所示，\snippetdoc 的可能解决方案是：

/**
* \file
* \section links "Useful Links"
* - \snippetdoc docs/mainpage.dox url_to_link1
* - \snippetdoc docs/mainpage.dox url_to_link2
*/

按照 OP 的指示，以下版本不起作用：

/**
* \file
* \brief     Some function definition
* \see       API reference on specific subject (more info: \snippetdoc docs/mainpage.dox url_to_link1)
*/

问题在于\snippetdoc 的定义是\snippetdoc <file-name> ( block_id )，其中(block_id) 意味着它会一直读取到行尾（参见doxygen 文档），因此结束) 是@987654331 的一部分@ 并且无法解决。

一个可能更好的实现可能是<block_id>，这样block_id 就是一个单词。问题在于它可能会破坏现有文档，例如block_id 中使用了空格或点。

这个问题有很多解决方案：

1) 将结束) 定义为block_id 的一部分（在不工作的版本中）：

[url_to_link1)]
<a href="linkToSomething">Link description</a>)
[url_to_link1)]

2) 将结束的) 放在下一行（定义可以保留在问题中）：

/**
* \file
* \brief     Some function definition
* \see       API reference on specific subject (more info: \snippetdoc docs/mainpage.dox url_to_link1
*            )
*/

3) 定义2个定义：

[url_to_link1)]
<a href="linkToSomething">Link description</a>)
[url_to_link1)]
[url_to_link1]
<a href="linkToSomething">Link description</a>
[url_to_link1]

I 通用解决方案 2) 是作为解决方案的首选解决方案。 block_id 之后的所有文本都必须在下一行。