{"id":5662,"date":"2023-09-29T05:07:57","date_gmt":"2023-09-29T04:07:57","guid":{"rendered":"https:\/\/www.baeldung.com\/java-doc-code-snippets"},"modified":"2023-09-29T05:07:57","modified_gmt":"2023-09-29T04:07:57","slug":"code-snippets-in-java-api-documentation","status":"publish","type":"post","link":"https:\/\/gamefootballmobileanimeiphone.com\/index.php\/2023\/09\/29\/code-snippets-in-java-api-documentation\/","title":{"rendered":"Code Snippets in Java API Documentation"},"content":{"rendered":"

\"\"<\/p>\n

\u00a01. Overview<\/h2>\n
<\/div>\n

Comprehensive documentation helps developers work with libraries easily. Javadoc<\/a> is a great tool that helps generate documentation for Java code. Java 18 introduced the @snippet<\/em> tag to easily integrate code snippets into documentation<\/strong>.<\/p>\n

In this tutorial, we’ll explore how to add code snippets into documentation using the @snippet<\/em> tag.<\/p>\n

2. Before the @snippet<\/em> Tag<\/h2>\n
<\/div>\n

Before Java 18, we could add code snippets in documentation using the @code<\/a> <\/em>tag. However, this came with some limitations.<\/p>\n

The @code<\/em> tag treats the code like normal text. It doesn’t validate code snippets and highlight syntax<\/strong>.<\/p>\n

3. Using the @snippet<\/em> Tag<\/h2>\n
<\/div>\n

Java 18 introduced the @snippet<\/em> tag to address the limitations of the @code<\/em> tag. It has features to highlight code syntax. <\/strong><\/p>\n

Further, it makes it easy to embed code in documentation<\/strong>. It also comes with features to add code from external sources to documentation<\/strong>.<\/p>\n

Additionally, code fragments can be validated using the Compiler Tree APIs.<\/p>\n

The @snippet<\/em> tag can be used in two different ways – in-line snippet and external code snippet<\/strong>.<\/p>\n

3.1. In-Line Code Snippets<\/h3>\n
<\/div>\n

The in-line code snippets help to add code snippets to a Javadoc comment by explicitly putting the code within the @snippet<\/em> tag<\/strong>.<\/p>\n

The @snippet<\/em> tag has opening and closing curly braces. The code snippets are written after the colon sign. Additionally, the code snippets must be within the curly braces:<\/p>\n

{@snippet : "placeholder for code snippets" }<\/code><\/pre>\n
Here’s an example of documentation using the in-line code snippets:<\/p>\n
\/**\r\n * The code below shows the content of {@code helloBaeldung()} method\r\n * {@snippet :\r\n * public void helloBaeldung() {\r\n *     System.out.println("Hello From Team Baeldung");\r\n * }\r\n * }\r\n *\/\r\npublic class GreetingsInlineSnippet {\r\n    public void helloBaeldung() {\r\n        System.out.println("Hello From Team Baeldung");\r\n    }\r\n}<\/code><\/pre>\n
In the above code, we add the helloBaeldung()\u00a0<\/em>method in the documentation. First, we define the @snippet<\/em> tag. Then, we write the code snippet within the tag.<\/p>\n
Here’s the generated\u00a0 Javadoc:\"an-in-line-snippet-to-show-hello-baeldung-method\"<\/a><\/p>\n
The above image shows an in-line code snippet embedded in documentation.<\/p>\n
3.2. External Code Snippets<\/h3>\n
<\/div>\n
Additionally, we can add to documentation code snippets from an external file or a class. First, we have to specify the region we want to add using the @start<\/em> and @end<\/em> tags<\/strong>.<\/p>\n
Let’s write some simple documentation that shows a method to implement binary search<\/a> in Java.<\/p>\n
First, let’s create a class named BinarySearch<\/em> with a method to implement binary search and specify the portion to add to the documentation:<\/p>\n
public class BinarySearch {\r\n    public int search(int[] list, int item) {\r\n        int index = Integer.MAX_VALUE;\r\n        int low = 0;\r\n        int high = list.length - 1;\r\n        \r\n        \/\/ @start region="binary"\r\n        while (low <= high) { \r\n            int mid = high - low; \r\n            int guess = list[mid]; \r\n            if (guess == item) { \r\n                index = mid; break; \r\n            } else if (guess > item) {\r\n                low = mid - 1;\r\n            } else {\r\n                low = mid + 1;\r\n            }\r\n            low++;\r\n        }\r\n        \/\/ @end region="binary"\r\n        return index;\r\n    }\r\n}<\/code><\/pre>\n
In the code above, we want to add the region named “binary<\/em>” to documentation in the GreetingsExternalSnippet<\/em> class. We use the @start<\/em> tag to mark the start region and the @end<\/em> tag to mark the end region.<\/p>\n
Furthermore, “binary<\/em>” is a unique name for the marked region, and it can be used to call the section in any Javadoc<\/strong>.<\/p>\n
Let’s add the code to a Javadoc comment in a GreetingsExternalSnippet<\/em> class:<\/p>\n
\/**\r\n * \r\n * External code snippet showing the loop process in binary search method.\r\n * {@snippet class="BinarySearch" region="binary"}\r\n *\/\r\n  \r\npublic class GreetingsExternalSnippet {\r\n    public void helloBinarySearch() {\r\n        System.out.println("Hi, it's great knowing that binary search uses a loop under the hood");\r\n    }\r\n}<\/code><\/pre>\n
Here, we call an external file using the @snippet<\/em> tag by giving the correct class name and the region name. Also, we need to place the external classes or files in a directory named snippet-files<\/em>\u00a0for the Javadoc command to recognize the path of the external file or class<\/strong>.<\/p>\n
To generate the Javadoc, we need to specify the folder snippet-files<\/em>\u00a0with the –snippet-path\u00a0<\/em>option to avoid errors while generating the documentation<\/strong>:<\/p>\n
$ javadoc -d doc com.baeldung.snippettag --snippet-path snippet-files<\/code><\/pre>\n
The command above generates the documentation.<\/p>\n
Here’s the generated Javadoc:\"external-snippet-tag-showing-while-loop-in-binary-search\"<\/a><\/p>\n
The section named binary<\/em> is successfully imported into the documentation.<\/p>\n
Notably, we can also import snippets from files like properties files, config files, etc., using the file attributes.<\/p>\n
Here’s an example that shows a properties file with a defined region:<\/p>\n
# @start region="zone"\r\nlocal.timezone = GMT+1\r\nlocal.zip = 94123\r\n# @end region="zone"<\/code><\/pre>\n
Next, let’s embed the defined “zone<\/em>” in a Javadoc comment by using the file<\/em> attribute:<\/p>\n
\/** \r\n * Time Zone \r\n * {@snippet file="application.properties" region="zone"} \r\n *\r\n *\/\r\npublic class GreetingsExternalSnippet {\r\n    public void helloBinarySearch() {\r\n        System.out.println("Hi, it's great knowing that binary search uses a loop under the hood");\r\n    }\r\n}<\/code><\/pre>\n
Here, we use the file<\/em> attribute to define the name of the file.<\/p>\n
Here’s the generated documentation:\"file-attribute-with-snippet-tag\"<\/a><\/p>\n
The above image shows the snippet from the properties file.<\/p>\n
3.3. @highlight<\/em> Tag<\/h3>\n
<\/div>\n
Furthermore, we can highlight a section of a code snippet with the @highlight<\/em> tag to call for attention<\/strong>.<\/p>\n
Let’s modify the helloBaeldung()<\/em> method to highlight the section that prints greetings to the console:<\/p>\n
\/** \r\n * {@snippet :\r\n * public void helloBaeldung() {\r\n *     System.out.println("Hello From Team Baeldung"); \/\/ @highlight\r\n * }\r\n * }\r\n *\/<\/code><\/pre>\n
Here, the @highlight<\/em> tag highlights the line where we declare it:\"highlighting-section-of-a-code\"<\/a><\/p>\n
Additionally, we can be more specific on the string to highlight:<\/p>\n
\/** \r\n * {@snippet :\r\n * public void helloBaeldung() {\r\n *     System.out.println("Hello From Team Baeldung"); \/\/ @highlight substring="println"\r\n * } \r\n * } \r\n *\/<\/code><\/pre>\n
Here, we highlight “println<\/em>” by using the substring<\/em> attribute:\"highlighting-a-specific-text-in-code-snippet\"<\/a><\/p>\n
Furthermore, we can extend the scope of the @highlight<\/em> tag by using the region<\/em> attribute and the @end<\/em> tag:<\/p>\n
\/**\r\n * highlighting texts on multiple lines\r\n * {@snippet :\r\n * public void helloBaeldung() {\r\n *     System.out.println("Hello From Team Baeldung"); \/\/ @highlight region substring="println"\r\n *     String country = "USA";\r\n *     System.out.println("Hello From Team " + country); \/\/ @end\r\n *     \r\n * }\r\n * }\r\n *\/<\/code><\/pre>\n
The above code uses the region<\/em> attribute to define the beginning of the scope of the substring to highlight. Finally, we use the @end<\/em> tag to mark the end of the scope.<\/p>\n
The generated documentation highlights the specified substring:\"highlight-tag-to-mark-multiple-strings\"<\/a><\/p>\n
Here, the substring “println<\/em>” is highlighted in the specified scope.<\/p>\n
3.4. @replace<\/em> Tag<\/h3>\n
<\/div>\n
The @replace<\/em>\u00a0tag helps to modify texts within a snippet<\/strong>.<\/p>\n
Let’s see an example that uses the @replace<\/em> tag:<\/p>\n
\/**\r\n * {@snippet :\r\n * public void helloBaeldung() {\r\n *     System.out.println("Hello From Team Baeldung"); \/\/ @replace regex='".*"' replacement="..."\r\n * }\r\n * }\r\n *\/<\/code><\/pre>\n
Here, we replace the displayed text with three dots:\"replacing-displayed-text-with-replace-tag\"<\/a><\/p>\n
This can be useful in a case where we want to modify the displayed text.<\/p>\n