如何 link 到目录的文档
how to link to documentation of directory
我添加了 \dir 注释以提供目录附加文档。但是我无法使用任何我知道的 doxygen linking 技术 link 访问该目录文档。我的问题是：我如何正确地 link 到目录的文档？
以下是我尝试过的片段。我收到两个警告，但没有生成 link。 doxygen 手册的自动链接部分讨论了 Links to other members，但没有提到 links 到目录。 link 是否支持访问目录文档？如果是这样，我是做错了什么还是这是一个错误？ （我现在正在使用 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
文档用于该目录，但似乎没有办法引用它。我真诚地感谢任何帮助。
link 到目录文档页面的正确方法是使用 \ref 命令。目录不支持使用 # 的显式 link。
/// \file
/// \brief Implements the vt application class.
///
/// This file is in the \ref cpp/vtutil directory.
此示例将生成 link 到 cpp/vtutil 文件夹的文档。但是，在使用绝对路径和带有 STRIP_FROM_PATH 的 doxygen 配置设置时确实需要小心。当我使用源代码树中的工作目录 运行 doxygen 时，我可以获得正确的 link 引用。但是当我从一个与源目录不同的构建目录 运行 并且需要使用 STRIP_FROM_PATH 时，我就有问题了。
Doxygen 对使用 \dir 命令记录目录时使用的路径非常宽容或灵活，但在使用 \ref 命令引用它时却相当挑剔。
我就是这样解决这个问题的，我认为这是 Doxygen 中的一个错误。
接受的解决方案对我不起作用。我发现 link 到目录的唯一方法是使用绝对路径名：
/// \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 解析的绝对路径，但此路径取决于当前的开发环境。
我添加了 \dir 注释以提供目录附加文档。但是我无法使用任何我知道的 doxygen linking 技术 link 访问该目录文档。我的问题是：我如何正确地 link 到目录的文档？
以下是我尝试过的片段。我收到两个警告，但没有生成 link。 doxygen 手册的自动链接部分讨论了 Links to other members，但没有提到 links 到目录。 link 是否支持访问目录文档？如果是这样，我是做错了什么还是这是一个错误？ （我现在正在使用 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
文档用于该目录，但似乎没有办法引用它。我真诚地感谢任何帮助。
link 到目录文档页面的正确方法是使用 \ref 命令。目录不支持使用 # 的显式 link。
/// \file
/// \brief Implements the vt application class.
///
/// This file is in the \ref cpp/vtutil directory.
此示例将生成 link 到 cpp/vtutil 文件夹的文档。但是，在使用绝对路径和带有 STRIP_FROM_PATH 的 doxygen 配置设置时确实需要小心。当我使用源代码树中的工作目录 运行 doxygen 时，我可以获得正确的 link 引用。但是当我从一个与源目录不同的构建目录 运行 并且需要使用 STRIP_FROM_PATH 时，我就有问题了。
Doxygen 对使用 \dir 命令记录目录时使用的路径非常宽容或灵活，但在使用 \ref 命令引用它时却相当挑剔。
我就是这样解决这个问题的，我认为这是 Doxygen 中的一个错误。
接受的解决方案对我不起作用。我发现 link 到目录的唯一方法是使用绝对路径名：
/// \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 解析的绝对路径，但此路径取决于当前的开发环境。