doxygen - 氧气的图像路径不正确

Question

tl; dr问题:

doxygen查找在doxygen注释中引用的图像的实际算法是什么？结果是，在以后的doxygen版本中不会被打破的最佳实践是什么？

细节:

我们正在尝试制定一项政策，在该政策中，与doxygen注释相关的任何图像都应本地化为引用，这意味着我们将在整个源代码树中分布图像。显然，我们需要确保适本地引用这些图像，并且doxygen可以找到它们以产生正确的文档。

doxygen documentation指出:

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

但是，在我进行修补时，我得出的结论是，这似乎并不完全正确。以下是一些实验结果:

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

实验

文件系统配置:

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

doxygen配置文件位于树的“根”(即 /full/path/)中，并且doxygen是从同一文件夹中执行的。 header.h引用位于同一树中的 images/image.png( /full/path/to/this)。在树的其他位置有一个同名的图像文件。 header.h行如下:

@file html [filename]

引用，其中 [filename]是以下之一:

image.png

images/image.png

./images/image.png

/full/path/to/this/images/image.png

然后我玩 IMAGE_PATH变量。

情况1: IMAGE_PATH =(即，未定义路径)。

加载了“错误”图片(other/iamges/image.png)

没有图片

没有图片

正确加载图像

情况2: IMAGE_PATH = /full/path(提供给root的路径，但没有提供给头文件的完整路径)。

正确加载图像

正确加载图像

正确加载图像

正确加载图像

情况3: IMAGE_PATH = /full/path/other(提供给root的路径，不包含头文件)。

加载了“错误”图片(other/iamges/image.png)

加载了“错误”图片(other/iamges/image.png)

加载了“错误”图片(other/iamges/image.png)

正确加载图像

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

推断的算法属性

相对路径仅在相对路径位于以IMAGE_PATH指定的路径为根的树中时有效。

在图像文件名可以解析为不同图像的情况下，doxygen似乎选择了与引用最接近的一个。

Answer 1

首先是第一件事...感谢您发布此信息，我开始认为自己缺少明显的东西。现在我知道我们至少有两个...

我试图在markdown文件中包含图片；这也许可以解释我得到的结果略有不同。另外，我仅使用\image命令进行了测试。最初，我只收到了一系列的“未找到图片”警告，但最终我获得了一些一致的积极结果，表明:

仅当IMAGE_PATH设置将直接指向指向图像所在的文件夹(无父文件夹)时，才找到该图像。手册通过建议IMAGE_PATH可能包含路径或文件

的集合，对此有所提示。

IMAGE_PATH可以表示为相对于运行DOXYGEN的位置的完整路径或

此外，为了“找到”镜像，文件名和路径应与的一部分匹配，即镜像

的实际全名和路径。

例如，给定 Markdown 页面和以下文件夹中的图像:

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

为了在“工作”文件夹中运行DOXYGEN时复制页面，IMAGE_PATH应该设置为以下之一:

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

/some-path/work/images/some/more/folders

图片/一些/更多/文件夹/the-image.png

图片/一些/更多/文件夹

在所有情况下，可以在 Markdown 页面中成功地将图像引用为“the-image.png”或“folders/the-image.png”，“more/folders/the-image.png”等。标准是实际文件路径和名称的引用匹配部分(虽然人们可能希望图像引用相对于其出现的markdown文件-这似乎是错误的)。

我再说一遍，这些测试是使用markdown文件进行的，在这种情况下，其机制可能与适用于源文件中引用的图像的机制不同。