10

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.

albert
  • 8,285
  • 3
  • 19
  • 32
Phil
  • 5,822
  • 2
  • 31
  • 60
  • I've created a directory cpp/vtutil, with a file dir.c and a file vt.c with respectively the content of the \dir and \file in it. I've set in the further default Doxyfile RECURSIVE to YES. I get only the message about the explicit link the \ref command links as far as I can see. – albert Jul 22 '15 at 16:45

2 Answers2

3

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.

albert
  • 8,285
  • 3
  • 19
  • 32
Phil
  • 5,822
  • 2
  • 31
  • 60
  • Do you have any further information on your problems and how to fix them? I cannot for the life of me get any links to directories to work. Doxygen just says "unable to resolve reference" no matter what I try, yet the documentation for the directories appears just fine under the "files" list. – Ben Farmer Apr 27 '18 at 09:34
  • I even tried grepping the xml for the files pages that contain working links to these folders, and using the link names I found there, but they don't seem to work when I use them with \ref... – Ben Farmer Apr 27 '18 at 09:39
  • Have you tried just my simple example and run doxygen in the source tree? You may want to ask a new question with exact details (in the question or a link). I have found that these things with doxygen change with new versions, so the more specific details the better. If you do post a new question, drop a comment and I will look at it. – Phil Apr 27 '18 at 12:49
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.

Cris Luengo
  • 55,762
  • 10
  • 62
  • 120
  • You wrote: "This is how I fixed this issue, which I would consider a bug in Doxygen." Is theer an issue for this in the doxygen issue tracker? And can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent. Please also specify the doxygen version used. – albert May 09 '19 at 11:43
  • @albert: I did find [this bug report](https://github.com/doxygen/doxygen/issues/6019), which links back to this question. I have not submitted an issue to the tracker because it takes quite an effort to make, you guys already have too much work on your plates, and I have a workaround I don’t mind using. But I appreciate your message and also all the work you guys put into this tool. – Cris Luengo May 09 '19 at 14:18