如何创建指向同一文件的 Doxygen 链接

Question

我想写一个 Doxygen 注释来命名该注释所在的文件。我希望 Doxygen 提供给我，而不是明确地写文件名。因此，如果我更改文件的名称，或将某些内容移动到不同的文件中，我不需要更改名称的硬编码实例。

举个具体的例子，假设我正在将 cmets 添加到 array.hpp 中的函数，并且我希望某些函数的注释显示“该函数只能在 array.hpp 中使用”。我希望能够写作

/**
 *  This function should only be used within @thisfile.
 */

其中@thisfile 是一个 Doxygen 表达式，它在文件 array.hpp 中转换为 array.hpp。

我查看了 Doxygen 文档，包括“自动链接生成/文件链接”和整个“特殊命令”部分，但我没有找到我要查找的内容。有这样的功能吗？

请注意，几周前在 Doxygen 邮件列表上提出了基本相同的问题。它没有收到任何回复。

Answer 1

一般

据我所知，此类功能不存在开箱即用。但是您可以通过在Doxyfile 中配置INPUT_FILTER 来添加它。文件的路径由 doxygen 作为参数传递给过滤器。过滤器可以使用它来将您的关键字（例如@thisfile）替换为文件的路径。

下面我将举例说明如何使用bash 实现这一点。其他 shell 或 Windows 的解决方案应该非常相似。

bash 的示例

1. 写一个简短的bash脚本infiltrate_filename.sh：

   #!/bin/bash
   pathToScript=`pwd`"/"
   sed -e "s:@thisfile:${1/$pathToScript/}:g" $1
   

   此脚本根据工作目录截断文件的路径。结果字符串用于替换您选择的关键字（此处为：@thisfile）。

2. 使您的脚本可执行：chmod +x infiltrate_filename.sh
3. 将Doxyfile 中的INPUT_FILTER 设置为INPUT_FILTER = ./infiltrate_filename.sh

就是这样！ ? 现在您可以在documentation blocks 中使用@thisfile，它将被文件路径替换。由于路径是相对于 Doxygen 的工作目录的，它们将 automatically be linked 指向文件。

注意事项

此解决方案假定过滤器脚本位于 doxygen 的工作目录中（例如 ~/my_project），并且 INPUT 文件位于工作目录的子目录中（例如 ~/my_project/src/foo/bar）。

我已经在一个最小的工作示例上测试了这个示例。我不是bash 或sed 专家。这个解决方案可能是可以改进的。