如何链接到目录文档

Question

如何链接到目录文档

10

我已经添加了一个\dir注释，以提供有关目录的其他文档。但是我无法使用我所知道的任何doxygen链接技术来链接到该目录文档。我的问题是：如何正确地链接到目录的文档？

以下是我尝试过的片段。我得到两个警告和没有生成的链接。 doxygen手册的自动链接部分讨论了链接到其他成员，但它没有提到链接到目录。是否支持链接到目录文档？如果是，我做错了什么，还是这是一个错误？（我现在正在使用1.8.10。 1.8.9.1表现相同。）

下面是我尝试过的内容。我已经使用了文档化目录：

/// \dir cpp/vtutil 
///      
/// \brief Brief description of the dir cpp/vtutil goes here
/// 
/// \details A more detailed description goes here. 
///

我使用以下方式引用目录：

/// \file   
/// \brief  Implements the vt application class.
/// 
/// This file is in the \ref cpp/vtutil directory.
/// What about #cpp/vtutil

以下是警告信息：

warning : unable to resolve reference to `cpp/vtutil' for \ref command
warning : explicit link request to 'cpp' could not be resolved

文档用于目录，但似乎没有方法可以引用它。非常感谢您的帮助。

- Phil

我创建了一个名为cpp/vtutil的目录，其中包含文件dir.c和vt.c，分别具有其内部的\dir和\file内容。我在进一步的默认Doxyfile中将RECURSIVE设置为YES。据我所见，我只收到关于显式链接\ref命令链接的消息。 - albert

2个回答

2

这是我解决这个问题的方法，我认为这是Doxygen中的一个bug。

接受的解决方案对我不起作用。我发现唯一链接到目录的方法是使用绝对路径名：

/// \brief Documentation linking to a directory
///
/// The files are in the \ref /home/user/project/include/subdir "include/subdir" directory.

通过使用\ref target "label"，我们避免在文档中出现完整路径，这当然是由开发环境提供的，与最终用户的安装目录无关。

但是现在我们仍然在源代码中有绝对路径。不同的开发者可能会有不同的路径，因此上述解决方案只适用于单个开发者。

相反，我在我的Doxyfile.in文件中添加了以下别名：

ALIASES += "link_to_subdir=\ref @PROJECT_SOURCE_DIR@/include/subdir \"include/subdir\""

这份文档现在看起来像这样：

/// \brief Documentation linking to a directory
///
/// The files are in the \link_to_subdir directory.

Doxyfile.in是一个文件，CMake解析它以生成Doxygen使用的Doxyfile。我认为这是使用Doxygen的一种相当标准的方式（其他构建生成器具有相同的功能，可以替代）。例如，我的Doxyfile.in包含以下内容：

PROJECT_NAME           = "@PROJECT_NAME@"
PROJECT_NUMBER         = @PROJECT_VERSION@
OUTPUT_DIRECTORY       = @CMAKE_INSTALL_PREFIX@/@DOCUMENTATION_OUTPUT@
INPUT                  = @PROJECT_SOURCE_DIR@/include

In CMake there is a command:

configure_file("${CMAKE_CURRENT_LIST_DIR}/documentation/Doxyfile.in" "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" @ONLY)

因此，CMake将在@PROJECT_SOURCE_DIR@处填充项目的根目录，导致在Doxygen解析文档时生成一个绝对路径，但是该路径取决于当前的开发环境。"最初的回答"

- Cris Luengo

你写道：“这就是我如何解决这个问题的方式，我认为这是Doxygen中的一个错误。” Doxygen的问题跟踪器中是否有此问题？您能否附上一个小的自包含示例（源代码+配置文件在tar或zip中），以便我们重现该问题？请不要添加外部链接，因为它们可能不持久。请还指定使用的Doxygen版本。 - albert

@albert：我找到了这个错误报告，它链接回了这个问题。我没有向跟踪器提交问题，因为这需要花费相当大的精力，而且你们已经有太多的工作要做了，而且我有一个解决方法，我不介意使用。但是我非常感谢你的信息，也感谢你们在这个工具上付出的所有努力。 - Cris Luengo

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Phil · Accepted Answer

连接到目录文档页面的正确方法是使用\ref命令。不支持使用#进行显式链接。

/// \file   
/// \brief  Implements the vt application class.
/// 
/// This file is in the \ref cpp/vtutil directory.

此示例将生成指向cpp/vtutil文件夹文档的链接。但是，在使用绝对路径和doxygen配置设置STRIP_FROM_PATH时需要小心。当我在源代码树中运行doxygen并将工作目录设置为该目录时，可以获得正确的链接引用。但是，当我从不同于我的源目录的构建目录运行并需要使用STRIP_FROM_PATH时，就会出现问题。

使用\dir命令记录目录时，Doxygen使用的路径相当宽容或灵活，但使用\ref命令引用它时则非常挑剔。