title: Incorrect image paths for doxygen
body: <p>tl;dr question:</p>
  
  <p>What is the <em>actual</em> 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?</p>
  
  <p>Details:</p>
  
  <p>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.</p>
  
  <p>The <a href="http://www.doxygen.nl/manual/commands.html#cmdimage" rel="noreferrer">doxygen documentation</a> states:</p>
  
  <blockquote>
    <p>doxygen will look for files in the paths (or files) that you specified after the IMAGE_PATH tag</p>
  </blockquote>
  
  <p>However, in my tinkering I've come to the conclusion that this doesn't seem strictly correct.  Here are some experimental results:</p>
  
  <p>================================================</p>
  
  <p>Experiment</p>
  
  <p>File system configuration:</p>
  
  <pre><code>/full/
     path/
        doxygen.cfg
        to/
           this/
              header.h
              images/
                 image.png
        other/
           images/
              image.png
  </code></pre>
  
  <p>The doxygen config file is in the "root" of the tree (i.e., <code>/full/path/</code>) and doxygen is executed from this same folder.<code>header.h</code> references <code>images/image.png</code> located in the same tree (<code>/full/path/to/this</code>).  There is an identically named image file located elsewhere in the tree.  <code>header.h</code> has the line: </p>
  
  <pre><code>@file html [filename]
  </code></pre>
  
  <p>reference where <code>[filename]</code> is one of the following:</p>
  
  <ol>
  <li><code>image.png</code></li>
  <li><code>images/image.png</code></li>
  <li><code>./images/image.png</code></li>
  <li><code>/full/path/to/this/images/image.png</code></li>
  </ol>
  
  <p>Then I play with the <code>IMAGE_PATH</code> variable.</p>
  
  <p>Case 1:<code>IMAGE_PATH =</code>  (i.e., no path defined).</p>
  
  <ol>
  <li>"Wrong" image loaded (other/iamges/image.png)</li>
  <li>no image</li>
  <li>no image</li>
  <li>Correct image loaded</li>
  </ol>
  
  <p>Case 2: <code>IMAGE_PATH = /full/path</code> (path provided to root, but not full path to header file).</p>
  
  <ol>
  <li>Correct image loaded</li>
  <li>Correct image loaded</li>
  <li>Correct image loaded</li>
  <li>Correct image loaded</li>
  </ol>
  
  <p>Case 3: <code>IMAGE_PATH = /full/path/other</code> (path provided to root which does <em>not</em> include the header file).</p>
  
  <ol>
  <li>"Wrong" image loaded (other/iamges/image.png)</li>
  <li>"Wrong" image loaded (other/iamges/image.png)</li>
  <li>"Wrong" image loaded (other/iamges/image.png)</li>
  <li>Correct image loaded</li>
  </ol>
  
  <p>================================================</p>
  
  <p>Inferred Algorithm Properties</p>
  
  <ol>
  <li>Relative paths only work if the relative path is in the tree rooted in a path specified in <code>IMAGE_PATH</code>.</li>
  <li>In the case where the image file name can resolve into different images, doxygen appears to pick the one "closest" to the reference.</li>
  </ol>