t4 - Doxygen:如何链接到用不受支持的语言编写的源文件？

Question

我们正在使用 Doxygen 为跨语言项目生成 HTML 文档。在某些文档中，我想链接到用 Doxygen 不支持的语言编写的文件的源代码(实际上，它是一个 Visual Studio T4 模板)。

目前，我只是在文档注释中写出文件名。

在 Doxyfile 中包含文件的扩展名使链接有效，但 Doxygen 完全误解了文件，并链接到这个被误解的文档，而不是源文件，这正是我想要的。

但是，如果我排除文件的扩展名，Doxygen 根本不会占用该文件。

是否有任何 Doxygen 命令可以直接链接到文件的源代码，而不是其文档？

我真的不在乎 Doxygen 是否为这个文件生成了错误的文档:只要我可以直接链接到文件的源而不是文档，我就会很高兴。文档本身显然不正确，因此生成页面并可能找到该页面并无害处。

有什么想法吗？

Answer 1

我不确定这是否是您正在寻找的答案，但以下几点希望有用:

• 您可以使用 \include 包含源代码块命令。来自 Doxygen 手册:

  \include <file-name>

  This command can be used to include a source file as a block of code. The command takes the name of an include file as an argument. Source files or directories can be specified using the EXAMPLE_PATH tag of Doxygen's configuration file.

  Using the \include command is equivalent to inserting the file into the documentation block and surrounding it with \code and \endcode commands.

• 另外，来自 this页

  Links to files.

  All words that contain a dot (.) that is not the last character in the word are considered to be file names. If the word is indeed the name of a documented input file, a link will automatically be created to the documentation of that file.

• 最后，来自 Doxygen FAQ :

  11. Doxygen automatically generates a link to the class MyClass somewhere in the running text. How do I prevent that at a certain place?

  Put a % in front of the class name. Like this: %MyClass. Doxygen will then remove the % and keep the word unlinked.

从最后两点来看，如果 Doxygen 发现它认为是文件名，它似乎会自动链接到文档文件。 %字符将阻止 Doxygen 执行此操作，但是您需要找到一种方法来链接到您包含在 \include 中的代码。 .

此外，请参阅我对您的问题的评论，了解如何停止 Doxygen 为您的 Visual Studio T4 模板生成文档 - 我认为如果您遵循评论中的建议，Doxygen 将不会自动放置指向该文件的链接(不正确) 文档。

编辑:正如问题评论中所讨论的，一种可能的解决方案是为源代码创建一个新页面并将源代码直接包含在此页面上。例如，可以使用

/*! \page src_code Visual Studio T4 Template
    \include src.tt
 */

这将在文档的“相关页面”选项卡下包含一个标题为“Visual Studio T4 模板”的页面，可以使用标签 src_code 对其进行引用。 (即使用 \ref src_code 链接到该页面/源代码)。

最后，如果您包含 C/C++ 代码，您可以附上 \include与 \code和 \endcode语法命令突出显示代码。