在 javadocs 中包含图像答案

【问题标题】：Including images in javadocs在 javadocs 中包含图像
【发布时间】：2012-06-02 11:56:10
【问题描述】：

我使用大量可视化的示例测试用例。有什么方便的方法可以将它们包含在我的 Java 源代码中并将它们链接到 Javadocs 中，这样我的 IDE 就可以在编码时自动显示它们（通过在我的 IDE 中调用 javadoc 渲染器功能？）

我尝试在 Java 源代码旁边放一张图片并使用 <img>，但它不接受（我使用的是 png）。

（注意 - 在这种情况下它在我的测试源中）

【问题讨论】：

为什么不向我们展示您尝试用一些代码做什么呢？使用edit 链接添加它。祝你好运！ :)
this 是你想要达到的目标吗？

标签： java image javadoc

【解决方案1】：

有点牵强，但您可以通过将图像转换为 Base64 来内联文档中的图像。它看起来像这样：

<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIA..." />

有在线工具可用于进行转换：

【讨论】：

您可以使用 Paulo 解释的普通图像，但这意味着要管理一个单独的文件。
inteliJ 看不到该图像
我在显示图像时也使用了base64编码。从 IntelliJ 运行应用程序时，图像有时显示为空白。但是，当应用程序在部署后单独运行时，同样适用。我做错了什么？

【解决方案2】：

由于你没有显示任何来源，我只能做一个玻璃球猜测......

对于文档所需的任何文件，应将它们放在包目录中名为 doc-files 的子目录中。然后这些将由 Javadoc 简单地复制到输出目录。然后在<img> 元素中使用相对路径。

我不确定您的 IDE 的 Javadoc 渲染器是否会这样做，但值得一试。

【讨论】：

谢谢 - 但这需要我运行 javadoc 实用程序，我希望避免这种情况（并且可能使这种情况变得不可能......）
将图像上传到imgur 之类的网站是一种享受：<img src="https://i.imgur.com/GPzGu1N.png" /> In action in IntelliJ
@BradTurek 这似乎是一个糟糕的计划。当某些随机网站移动或关闭时，文档不应消失。
使用最新的 IntelliJ (2020)，此功能开箱即用（参见blog.jetbrains.com/idea/2020/03/intellij-idea-2020-1-eap8） - 您可以将它们放置在任何路径中，渲染无关紧要，您只需要引用它们正确的相对路径（即 src='doc-files/img.png'）。注意：如果您使用的是 Scala，ScalaDoc 存在一个问题，该问题最近已修复（修复可能需要几个月才能进入稳定的插件版本）。

【解决方案3】：

使用 Eclipse Luna，以下对我有用。

com
- 公司
  - 一些包
    - 文档文件
      - 图像.png
    - Test.java

现在在 Test.java 的 javadoc 中：

/**
 * <img src="./doc-files/image.png" />
 */

Eclipse 会在弹出帮助、鼠标悬停时以及 Javadoc 视图中显示图像。

您甚至可以将style="width: 100%;" 添加到img 标记中，以便图像调整为视图/弹出窗口大小。

【讨论】：

Android Studio 3.0（又名 IntelliJ）在“快速文档”弹出窗口中显示图像。

【解决方案4】：

为了扩展 Vsevolod Golovanov 和 Paulo Ebermann 的上述回答，这里有一个具体的例子和进一步的阐述。

Javadocs 文档指出：

要包含未处理的文件，请将它们放在名为 doc-files 的目录中，该目录可以是包含源文件的任何包目录的子目录。

如果您将图像文件放在该文件夹中，Javadocs HTML 文件将可以通过生成的 HTML 的相对路径访问它们。

因此，如果您的项目名为 MyProject 并且您要添加 Javadoc 注释的类是 org.foo.app.MyApp，则其源文件夹是 MyProject/src/org/foo/app/MyApp.java 并且你想在它的 Javadoc 中包含 MyImage.jpg，那么：

创建文件夹MyProject/src/org/foo/app/doc-files，并将图像文件放入其中。

此时您的 Javadocs 文本可以引用它：

<img src="doc-files/MyImage.jpg" width="500" alt="description of MyImage">

Javadocs 生成的 HTML 将被相应地编码。

注意“宽度”属性，允许缩放图像。高度按比例缩放。

当您运行 Javadocs 时，doc-files 文件夹将全部复制到 Javadocs 输出文件夹，并且其中的资源可供 HTML 使用。

【讨论】：

【解决方案5】：

试试这个方法

/**
 * @author KamyninSA
 * @version 1
 * <p><b>Description</b></p>
 * <p><img src="{@docRoot}/../src/test/resources/doc-files/ads.png" alt="alternative directory"></p>
 * */

【讨论】：

【解决方案6】：

稍微扩展一下 Paŭlo 的回答，假设这里的 maven 构建对我来说适用于 JDK-8（更严格的 HTML 验证），并规定您愿意运行 javadoc 工具。

不幸的是，使用 Netbeans 我在 IDE 的 javadoc 弹出窗口中看不到图像，我刚刚打开了 this netbeans bug。

假设这是 com.foo.File.java 的 javadoc 的一部分（注意没有 img 结束标记，这是 w3schools 的正确方式）：

<img src="doc-files/foo.png" alt="Foo">

在 maven 目录结构中，您会在此处找到图像：src/main/javadoc/com/foo/doc-files/foo.png

最后，在 pom.xml 中（注意 docfilessubdirs 设置为 true）：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>2.10.3</version>
            <configuration>
                <docfilessubdirs>true</docfilessubdirs>
            </configuration>
        </plugin>
        ...

【讨论】：

【解决方案7】：

我偶然发现了这个问题，因为我也想显示我的图标预览。看完答案，我还不满意，自己试了一下。这就是我现在得到的：

     /**
     * <img src="../../../../../../resources/com/my/project/client/images/myImage.png"><br>
     * Icon for myImage.
     *
     * @return the icon
     */

像这样，我不需要管理比以前更多的图像，只需转到实际图像所在的文件夹即可。

【讨论】：