Including images in javadocs

Question

I work with a lot of sample test cases that are visual. Is there any convenient way to include them in my Java source and link them in Javadocs, so my IDE can automatically

Answer 1

Try this way

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

Answer 2

A bit far fetched, but you can inline the images in the documentation by converting them into Base64. It would look like this:

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

There are online tools available to do the conversion:

• http://www.base64-image.de
• http://daturi.me
• http://www.freeformatter.com/base64-encoder.html

Answer 3

With Eclipse Luna the following works for me.

• com
  • company
    • somepackage
      • doc-files
        • image.png
      • Test.java

Now in Test.java's javadoc:

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

And Eclipse shows the image both in popup help, when you hover the mouse, and in the Javadoc View.

You can even add style="width: 100%;" to the img tag, so the image adjusts to the view/popup size.

Answer 4

To expand a little on Paŭlo's answer assuming a maven build here is what worked for me with JDK-8 (stricter HTML validation), with the stipulation that you're willing to run the javadoc tool.

Unfortunately with Netbeans I cannot see the image in the IDE's javadoc popup, I just opened this netbeans bug.

Assume this is part of the javadoc for com.foo.File.java (notice no img end tag, which is the right way per w3schools):

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

In the maven directory structure you'll find the image here: src/main/javadoc/com/foo/doc-files/foo.png

And last, in the pom.xml (notice docfilessubdirs is set to 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>
        ...

Answer 5

To expand a bit on Vsevolod Golovanov and Paulo Ebermann's answer above, here is a concrete example and further elaboration.

The Javadocs documentation states:

To include unprocessed files, put them in a directory called doc-files which can be a subdirectory of any package directory that contains source files.

If you place the image files in that folder they will be available to the Javadocs HTML files via the relative path from the generated HTML.

So, if your project is named MyProject and the class you are adding Javadoc commentary to is org.foo.app.MyApp, the source folder for which is MyProject/src/org/foo/app/MyApp.java and you want to include MyImage.jpg in it's Javadoc, then:

Create the folder MyProject/src/org/foo/app/doc-files, and place the image file in it.

At that point your Javadocs text can reference it thus:

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

And the Javadocs-generated HTML will reflect be coded accordingly.

Note the "width" attribute, allowing scaling of the image. The height is scaled proportionally.

When you run Javadocs, the doc-files folders will all be copied to the Javadocs output folders and the resources within them will be available for use by the HTML.

Answer 6

As you didn't show any sources, I can only do a glass-ball guess ...

For any files which are needed for documentation purposes, one should put them in a subdirectory named doc-files of your package directories. These will then be simply copied by Javadoc to the output directory. Then use a relative path in the <img> element.

I'm not sure if your IDE's Javadoc renderer will do the same, but it is worth a try.