Linking
Adding links in code can be done via the @link tag. The common arguments are substring=”…” and target=”…”. For instance, the following snippet provides a link for the text Calibrate that navigates in documentation to the description of Calibrate.at() method:
Figure 2.18 – Adding links in code
Next, let’s see how we can modify the code’s text.
Modifying code’s text
Sometimes we may need to alter the code’s text. For instance, instead of Telemeter.Calibrate.at(0.00001, “HIGH”); we want to render in documentation Telemeter.Calibrate.at(eps, “HIGH”);. So, we need to replace 0.00001 with eps. This is the perfect job for the @replace tag. Common arguments include substring=”…” (or, regex=”…”) and replacement=”…”. Here is the snippet:
Figure 2.19 – Replacing code’s text
If you need to perform multiple replacements in a block of code then rely on regions. In the following example, we apply a regular expression to a block of code:
Figure 2.20 – Applying multiple replacements via a simple regex and an anonymous region
If you need to perform more replacements on the same line then just chain multiple @replace tags (this statement applies to all tags such as @highlight, @link, and so on).
Using external snippets
So far, we have used only inlined snippets. But, there are scenarios when using inlined snippets is not a convenient approach (for instance, if we need to repeat some parts of the documentation) or is not possible to use them (for instance, if we want to embed /*…*/ comments which cannot be added in inlined snippets).For such cases, we can use external snippets. Without any further configurations, JDK automatically recognizes external snippets if they are placed in a subfolder of the package (folder) containing the snippet tag. This subfolder should be named snippet-files and it can contain external snippets as Java sources, plain text files, or properties files. In the following figure, we have a single external file named MainSnippet.txt:
Figure 2.21 – External snippets in snippet-files
If the external snippet is not a Java file then it can be loaded via {@snippet file …} as follows:
{@snippet file = MainSnippet.txt}
{@snippet file = “MainSnippet.txt”}
{@snippet file = ‘MainSnippet.txt’}
But, we can also customize the place and folder name of external snippets. For instance, let’s place the external snippets in a folder named snippet-src as follows:
Figure 2.22 – External snippets in a custom folder and place
This time, we have to instruct the compiler where to find the external snippets. This is done by passing to javadoc the –snippet-path option. Of course, you can pass it via the command line, via your IDE, or as via maven-javadoc-plugin as follows:
<additionalJOption>
–snippet-path C:\…\src\snippet-src
</additionalJOption>
This path is relative to your machine so feel free to adjust it accordingly in pom.xml.Next, the AtSnippet.txt and ParamDefaultSnippet.properties can be loaded exactly as you saw earlier for MainSnippet.txt. However, loading Java sources, such as DistanceSnippet.java can be done via {@snippet class…} as follows:
{@snippet class = DistanceSnippet}
{@snippet class = “DistanceSnippet”}
{@snippet class = ‘DistanceSnippet’}
But, do not add explicitly the .java extension because you’ll get an error as file not found on source path or snippet path: DistanceSnippet/java.java:
{@snippet class = DistanceSnippet.java}
When using Java sources as external snippets pay attention to the following note:
Even if the pre-defined snippet-files name is an invalid name for a Java package, some systems may treat this folder as being part of the package hierarchy. In such cases, if you place Java sources in this folder you’ll get an error such as Illegal package name: “foo.buzz.snippet-files”. If you find yourself in this scenario then simply use another folder name and location for the documentation external snippets written in Java sources.
Regions in external snippets
The external snippets support regions via @start region=… and @end region=…. For instance, in AtSnippet.txt, we have the following region:
// This is an example used in the documentation
// @start region=only-code
Telemeter.Calibrate.at(0.00001, “HIGH”);
// @end region=only-code
Now, if we load the region as:
{@snippet file = AtSnippet.txt region=only-code}
We obtain only the code from the region without the text, // This is an example used in the documentation.Here is another example of a properties file with two regions:
# @start region=dist
sc=[0,0]
ec=[0,0]
interpolation=false
# @end region=dist
# @start region=at
eps=0.1
type=null
# @end region=at
The region dist is used to show in the documentation the default values for the arguments of the distance() method:
Figure 2.23 – Using the dist region
And, the at region is used to show in the documentation the default values for the arguments of the at() method:
Figure 2.24 – Using the ‘at’ region
In external snippets, we can use the same tags as in the inlined snippets. For instance, in the following figure you can see the complete source of AtSnippet.txt:
Figure 2.25 – Source of AtSnippet.txt
Notice the presence of @highlight and @replace.
Starting with JDK 19, the Javadoc search feature was also improved. In other words, JDK 19+ can generate a standalone search page for searching in the Javadoc API documentation. Moreover, the search syntax has been enhanced to support multiple search words.
You can practice these examples in the bundled code.