如何链接到目录的文档

Question

我添加了一个\dir 注释来为目录提供额外的文档。但是我无法使用我知道的任何 doxygen 链接技术链接到该目录文档。我的问题是：如何正确链接到目录的文档？

下面是我尝试过的sn-p。我收到两个警告，但没有生成链接。 doxygen 手册的自动链接部分讨论了Links to other members，但它没有提到到目录的链接。是否支持链接到目录文档？如果是这样，我做错了什么还是这是一个错误？ （我现在正在使用 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

文档用于目录，但似乎没有办法引用它。我真诚地感谢任何帮助。

Answer 1

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

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

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

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

Answer 2

这就是我解决此问题的方法，我认为这是 Doxygen 中的一个错误。

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

/// \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

在 CMake 中有一个命令：

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

因此，CMake 将填写项目的根目录，其中显示为@PROJECT_SOURCE_DIR@，从而导致 Doxygen 解析的文档中的绝对路径，但该路径取决于当前的开发环境。