In the part 1 we’ve seen how we can use inline snippets in Javadoc and how to control their appearance with regions and highlighting. While such usage should be enough for a lot of use-cases, from time to time we’ll need more power, for example to include snippets with block comments. In such cases, external snippets come to the rescue. Let’s see how to use them!
Where to put external snippets
By default, external snippets should be in a snippet-files directory immediately below your package source files. In this example, my package is org.thejavaguy and it contains 4 Java source files. Snippet file is called ExternalSnippetDemo.java and it is located in the snippet-files one level below source files:
1# ivanmilosavljevic @ ARTEMIS in ~/src/java18-school [13:36:11]
2$ tree
3.
4└── src
5 └── org
6 └── thejavaguy
7 ├── CharsetDemo.java
8 ├── Main.java
9 ├── Point.java
10 ├── SWSDemo.java
11 └── snippet-files
12 ├── ExternalSnippetDemo.java
13 ├── ExternalSnippetWithRegions.java
14 └── external-html-snippet.html
How to use an external snippet
With that in place, we can use our old friend @snippet tag and its class attribute to include the entire content of the ExternalSnippetDemo.java. In the file Main.java it looks like this:
1/**
2 * Demo of external snippet.
3 *
4 * {@snippet class=ExternalSnippetDemo
5 * }
6 */
7public void demoExternalSnippet() {
8}
Now we can generate Javadoc with javadoc -d doc -sourcepath src/ org.thejavaguy and see the result:
The most visible difference comparing to the internal snippet is that block comment is now rendered.
Usage of non-Java external snippet
Snippets don’t have to be Java files, we can use almost any file as an external snippet source. In that case we can’t write class=… in our source but must use file=… instead:
1/**
2 * Demo of external non-Java snippet.
3 *
4 * {@snippet file="external-html-snippet.html" lang="html"}
5 */
6public void demoExternalHtmlSnippet() {
7}
Javadoc will then show:
Using only parts of external snippet
Sometimes we’ll want to use just a portion of an external snippet. This is possible by using regions in almost the same way as in internal snippets. The snippet itself shall define a named region by using @start markup tag and its region attribute, for example @start region=reg0. Then, in our source file whose Javadoc should display that snippet we will use region attribute of a @snippet tag to refer to that region, for example @snippet region=reg0. Concretely, in the external file we’ll have following lines:
1…
2// @start region="reg0"
3System.out.println("Inside region reg0");
4System.out.println("Another line of text");
5// @end region="reg0"
6…
And in our main file, code will look like:
1/**
2 * Demo of external snippet with regions.
3 *
4 * {@snippet class=ExternalSnippetWithRegions region=reg0
5 * }
6 */
7public void demoExternalSnippetWithRegions() {
8}
Finally, generated Javadoc looks like:
Formatting/linking within external snippet
Unfortunately there is one problem with highlighting within external snippets. We can’t define region with @highlight region=reg1 (or @link region=reg1 or @replace region=reg1) and refer to that region within main source file. The only way to define a region in external snippet is @start region=reg1. Consequence is that we can’t apply highlighting to the whole region but only to one line! Since this is possible in internal snippets, I consider this a bug in the JDK. Hopefully it will be resolved in one of the next versions.
Official JEP specification
If you want to dive deeply into specification of this feature, you may find it in JEP 413.
Dear fellow developer, thank you for reading this article about external snippets in Javadoc. Until next time, TheJavaGuy saluts you!
Comments