how to link to documentation of directory - doxygen

Question

I have added a \dir comment to give a directory additional documentation. But I am unable to link to that directory documentation using any of the doxygen linking techniques that I know. My question is: how do I properly link to the documentation of a directory?
Below is a snippet of what I have tried. I get two warnings and no generated links. The Automatic Linking section of doxygen manual discusses Links to other members, but it does not mention links to dirs. Is linking to directory documentation supported? If so, am I doing something wrong or is this a bug? (I am using 1.8.10 right now. 1.8.9.1 behaved the same way.)
Here is what I have tried. I have documented the directory using
/// \dir cpp/vtutil
///
/// \brief Brief description of the dir cpp/vtutil goes here
///
/// \details A more detailed description goes here.
///
And I reference the directory using
/// \file
/// \brief Implements the vt application class.
///
/// This file is in the \ref cpp/vtutil directory.
/// What about #cpp/vtutil
Here are the warnings:
warning : unable to resolve reference to `cpp/vtutil' for \ref command
warning : explicit link request to 'cpp' could not be resolved
The documentation is used for the directory, but there does not seem to be a way to reference it. I sincerely appreciate any help.

Answer 1

The correct way to link to the documentation page for a directory is to use the \ref command. Explicit links using # are not supported for directories.
/// \file
/// \brief Implements the vt application class.
///
/// This file is in the \ref cpp/vtutil directory.
This example will generate a link to the documentation of the cpp/vtutil folder. One does, however, need to be careful when using absolute paths and the doxygen configuration setting with STRIP_FROM_PATH. When I run doxygen with the working directory in the source tree, I can get the correct link reference. But when I run from a build directory, which is different from my source directory, and need to use STRIP_FROM_PATH, then I have problems.
Doxygen is pretty forgiving or flexible with the path used when documenting a directory with the \dir command, but it is rather picky when referencing it with the \ref command.

Answer 2

This is how I fixed this issue, which I would consider a bug in Doxygen.
The accepted solution doesn't work for me. The only way I have found to link to a directory is using the absolute path name:
/// \brief Documentation linking to a directory
///
/// The files are in the \ref /home/user/project/include/subdir "include/subdir" directory.
By using \ref target "label", we avoid having the full path in the documentation, which of course is given by the development environment and unrelated to the end user's installation directory.
But we now still have the absolute path in the sources. A different developer will likely have a different path, so that the above solution is only usable by a single developer.
Instead, I added to my Doxyfile.in file the following alias:
ALIASES += "link_to_subdir=\ref #PROJECT_SOURCE_DIR#/include/subdir \"include/subdir\""
The documentation now looks like this:
/// \brief Documentation linking to a directory
///
/// The files are in the \link_to_subdir directory.
Doxyfile.in is a file that CMake parses to generate the Doxyfile that is used by Doxygen. I think it is a fairly standard way of using Doxygen (other build generators have the same functionality, and could be used instead). For example, my Doxyfile.in contains stuff like:
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)
Thus, CMake will fill in the project's root directory where it says #PROJECT_SOURCE_DIR#, leading to an absolute path in the documentation as parsed by Doxygen, but with this path being dependent on the current development environment.