Incorrect image paths for doxygen

Question

tl;dr question:

What is the actual algorithm doxygen uses to find images referenced to in doxygen comments? And the corollary, what's considered best practice which won't break in future doxygen versions?

Details:

We're trying to institute a policy where any images associated with doxygen comments should be localized to the reference, which means we'll have images distributed throughout the source tree. Obviously, we need to make sure that we refer to the images appropriately and that doxygen can find them to produce the correct documentation.

The doxygen documentation states:

doxygen will look for files in the paths (or files) that you specified after the IMAGE_PATH tag

However, in my tinkering I've come to the conclusion that this doesn't seem strictly correct. Here are some experimental results:

================================================

Experiment

File system configuration:

/full/
   path/
      doxygen.cfg
      to/
         this/
            header.h
            images/
               image.png
      other/
         images/
            image.png

The doxygen config file is in the "root" of the tree (i.e., /full/path/) and doxygen is executed from this same folder.header.h references images/image.png located in the same tree (/full/path/to/this). There is an identically named image file located elsewhere in the tree. header.h has the line:

@file html [filename]

reference where [filename] is one of the following:

1. image.png
2. images/image.png
3. ./images/image.png
4. /full/path/to/this/images/image.png

Then I play with the IMAGE_PATH variable.

Case 1:IMAGE_PATH = (i.e., no path defined).

1. "Wrong" image loaded (other/iamges/image.png)
2. no image
3. no image
4. Correct image loaded

Case 2: IMAGE_PATH = /full/path (path provided to root, but not full path to header file).

1. Correct image loaded
2. Correct image loaded
3. Correct image loaded
4. Correct image loaded

Case 3: IMAGE_PATH = /full/path/other (path provided to root which does not include the header file).

1. "Wrong" image loaded (other/iamges/image.png)
2. "Wrong" image loaded (other/iamges/image.png)
3. "Wrong" image loaded (other/iamges/image.png)
4. Correct image loaded

================================================

Inferred Algorithm Properties

1. Relative paths only work if the relative path is in the tree rooted in a path specified in IMAGE_PATH.
2. In the case where the image file name can resolve into different images, doxygen appears to pick the one "closest" to the reference.

Answer 1

First thing first... thanks for posting this, I was starting to think I was missing something obvious. Now I know there are at least two of us...

I was attempting to include a picture in a markdown file; this may explain the slightly different results I got. Also, I tested with \image command only. At first I only got a long series of "image not found" warnings, but eventually I reached some consistent positive results suggesting that:

1. The image is only found when IMAGE_PATH setting points directly to the folder where the image is (no parent folder). The manual slightly hints towards this by suggesting that IMAGE_PATH may ba a collection of paths or files
2. IMAGE_PATH can be expressed as a full path or relative to the location where DOXYGEN is run
3. Moreover, in order for the image to be "found", the file name and path should match a part of the actual full name and path of the image

For instance, given a markdown page and an image in the following folders:

/some-path/work/my-page.md
/some-path/work/images/some/more/folders/the-image.png

In order to copy the page while running DOXYGEN in the "work" folder, IMAGE_PATH should be set as one of the following:

• /some-path/work/images/some/more/folders/the-image.png
• /some-path/work/images/some/more/folders
• images/some/more/folders/the-image.png
• images/some/more/folders

In all cases, the image can be successfully referenced in the markdown page as either "the-image.png" or "folders/the-image.png", "more/folders/the-image.png" etc. The criteria is the reference matching part of the actual file path and name (while one could expect the image reference to be relative to the markdown file it appears in - this seems wrong).

I say again, these tests were conducted using a markdown file, and it's possible in this case the mechanics be different from the one applicable to images referenced in source files.