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!
As Java developers our job is not only to write working code but also to document it properly. Since its beginnings Java provided us with the javadoc
tool which generates this documentation from the specially formatted documentation comments we wrote in the source code. In these documentation comments we use various tags to document parameters, return values, exceptions thrown etc. It is often the case that we must include a code snippet to show intended usage of our code. Until Java 18 we relied on the @code
tag, perhaps in combination with <pre>…</pre>
if we needed multi-line snippets. But now we have a better way and that is by using new @snippet
tag. Let’s see its basic usage in action!