11

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 ?

Community
  • 1
  • 1
Marged
  • 10,577
  • 10
  • 57
  • 99

2 Answers2

12

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.

Marged
  • 10,577
  • 10
  • 57
  • 99
  • Hey, this should may not be used in normal code because the image do not change according to chages of the real class-hierarchy but i will use it in generated-code, thanks for the hint! – Grim Sep 14 '16 at 07:31
  • The docs just say docRoot expands to "the relative path to the generated document's (destination) root directory", so where do I put a file in my project hierarchy so it will get picked up when the javadocs are generated? – ThatAintWorking Oct 20 '18 at 00:11
3

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" />
 */
Grim
  • 1,938
  • 10
  • 56
  • 123
  • 1
    base64 encoding the image is not ideal because every time the image changes I have to update the javadoc. And depending on the size of the image the java files will grow considerably.Besides class hierarchies I plan to add more images that can help the programmer to understand what the classes can be used to. So creating class hierarchies from source is not an option. Neither is ascii art ;-) – Marged Feb 26 '15 at 15:07