how to link to documentation of directory

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.

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.