How to include images into javadoc and reference them

Question

I checked the manual of javadoc and read some posts here on stackoverflow (for example Including images in javadocs) but was unable to get a satisfactory result

I want to provide an image inside my javadoc that should be packaged with the created html. Here are the steps I take:

• create a doc-files directory below src/main/java (this is a gradle project in STS)
• place a file named classhierarchy.png into the freshly created directory
• add <img src="doc-files/classhierarchy.png"> to the javadoc of my class de.company.some.more.levels.MyClass
• create the javadoc

I can see that the png file gets copied to C:\temp\NameOfProject\doc\doc-files but it can't be displayed because the img-link is relative to the package: c:/temp/NameOfProject/doc/de/company/some/more/levels/doc-files/classhierarchy.png

I know that I could fix this by prefixing the path with many /../../ but I would have to adapt this if the package depth changes:

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

The second thing I don't like is the fact that directory doc-files is in the same path my source code is.

How can I link and provide the images elegantly ?

Answer 1

I can at least provide a solution for the abundant ".."s. Instead of writing:

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

we can use:

<img src="{@docRoot}/doc-files/classhierarchy.png">

This will instruct javadoc to insert the ".." itself, so I don't have to count myself ;-) and I don't have to adapt the ".."s when package structure changes. The parameter @docroot can be used in the code and on the command line, for details see the docs

In my tests this worked with the generated html and live inside Eclipse.

Answer 2

Often images speaks more than words. But a classhierarchy can change without effect to the image itself. Maybe you use other documentation technics like maven's site.

In your case its a bw-image right? Maybe you better use ascii-art.

Small images can also be used inline like this:

/**
 * Foobar.<br />
 * <img src=
 * "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADIAAAAyCAIAAACRXR/mAAAAAXNSR0IArs4c6QAAAA
 * RnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAADTSURBVFhH7c9BCsNADEPR3P9aPVjr5KukOBAEnkI
 * WejtDR/ndnuu9Qu28FqEqWR6qkuWhKlkeqpLloSpZHqqS5aEqWR6qkuWhKlkeqv6S1c5717c7Dc/Ujla/uzoM7feci
 * 7PYLJwOPWgLGp6pnd8PFL7h0IPDeWp4RlsLaXimdq7/26QHh/PU8EzttG9wOvSgLWh4pnYYLczqMLTfc67PKu28d32
 * 70/BM7Wh1jKpkeahKloeqZHmoSpaHqmR5qEqWh6pkeahKloeqZHmoemrW42zbB+06mptY9nu7AAAAAElFTkSuQmCC" />
 */