38

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 show them while coding (by invoking a javadoc renderer feature in my IDE?)

I tried putting an image next to the Java source and using <img>, but it's not taking (I used a png).

(note - it's in my test sources in this case)

jamesmortensen
  • 33,636
  • 11
  • 99
  • 120
ianpojman
  • 1,743
  • 1
  • 15
  • 20

7 Answers7

35

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:

Emmanuel Bourg
  • 9,601
  • 3
  • 48
  • 76
  • You can use a normal image as explained by Paulo, but that means a separate file to manage. – Emmanuel Bourg May 28 '12 at 23:27
  • 7
    inteliJ does't see that image – mariopce Feb 22 '16 at 11:54
  • I too used base64 encoding in displaying image. When application is run from IntelliJ the image is shown sometimes as blank. But the same works when the application is run in isolation after deploying. Anything wrong that I'm doing? – Kiran Aug 11 '18 at 07:11
  • 1
    Here in the 2022 future, IntelliJ *does* support base64-encoded images in the Javadocs. – Brad Turek Oct 20 '22 at 21:42
28

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.

Paŭlo Ebermann
  • 73,284
  • 20
  • 146
  • 210
  • thanks - but that requires me to run the javadoc utility, which i hoped to avoid (and probably makes this situation impossible...) – ianpojman May 28 '12 at 23:16
  • 2
    Uploading the image to a site like [imgur](https://imgur.com/) works a treat: `` [In action in IntelliJ](https://i.imgur.com/WPtqCjV.png) – Brad Turek Feb 01 '18 at 05:15
  • 9
    @BradTurek that seems like a bad plan. Documentation should not disappear when some random website moves or closes down. – Brad Mace Aug 23 '19 at 14:17
  • 3
    With the recent IntelliJ (2020) this works out of the box (cf. https://blog.jetbrains.com/idea/2020/03/intellij-idea-2020-1-eap8/) - you can place them in any path, the rendered does not care, you only need to reference them with a proper relative path (i.e. as src='doc-files/img.png'). Note: if you are working with Scala, there was an issue with ScalaDoc, which was fixed recently (it may take a few months before the fix will find its way into the stable plugin version). – Suma Jul 22 '20 at 07:39
19

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.

Paŭlo Ebermann
  • 73,284
  • 20
  • 146
  • 210
Vsevolod Golovanov
  • 4,068
  • 3
  • 31
  • 65
7

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.

Roger Neyman
  • 161
  • 2
  • 3
5

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>
 * */
Dmitry
  • 6,716
  • 14
  • 37
  • 39
Сергей Камынин
  • 51
  • 1
  • 2
  • Using an IDE like IntelliJ, {@docRoot} references the root folder with all the java source files, for example src/main/java. With the Javadoc tag [{@docRoot}](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#docRoot) you can save all images for the javadoc at a centralized place and always reference them in the same way. If you have a folder /src/main/resources/javadoc containing your image files, then you can use `` in your javadoc in your java class file. – Julia Hinßen IT.NRW Aug 09 '22 at 12:56
3

I stumbled upon this question as I as well wanted to show a preview of my icons. After reading the answers, I was not yet satisfied and tried it for myself. That's what I now got:

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

like this I don't need to manage more images than before by simply going to the folder the actual images lie in.

BAERUS
  • 4,009
  • 3
  • 24
  • 39
2

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>
        ...
Jason
  • 2,579
  • 1
  • 17
  • 19