Java 18 Snippet Tag with Example

In Java 18, the snippet tag was introduced for addressing the drawbacks of the code tag. Java 18 added Snippets of Code in the API documentation of Java in the form of a new feature.

The JavaDoc's Standard Doclet contains the @snippet tag in Java and it makes it easier for adding the source code in the documentation of API. The Snippet tag in Java is an alternate option for the methods which are easily usable, provider higher strength and highly adaptable.

Explanation

The Javadoc tool will be utilized for rendering the body of the code and convert it into a HTML code. The disadvantage of not highlighting syntax, consisting markups of HTML, not handling indentation issues are few of the drawbacks of this method or technique. The snippet tag was introduced for addressing the drawbacks of the code tag. There are mainly two types of Snippets in Java and they are: Inline and External Snippets. Let us understand about them in detail with the help of few Java example programs.

Inline Snippets

A fragment of text which can be a source code or different type of structural text can be enclosed with the help of @snippet tag by using its simplest type of syntax.

The text of the snippet tag will be rendered by the generated documentation in the form of a HTML code. Few special characters like < and > will not be escaping with the entities of HTML.

Filename: InlineSnippet.java

/*
 Java program for demonstrating inline snippet in Javadoc.
 It has a method that performs addition of two integer numbers.
*/
public class InlineSnippet{
    /*
    The addition of two integer values is performed and result is returned.
	<p>Snippet:
    {@snippet InlineSnippet#AddNumbers}
    int a - the first integer parameter.
    int b - the second integer parameter.
    @return The result calculated by adding both parameters.
    */
    public int AddNumbers(int a, int b) {
        return a + b;
    }
	public static void main(String[] args)
	{
		InlineSnippet ob1 = new InlineSnippet();
		int result;
		result = ob1.AddNumbers(10,20);
		System.out.println("The Result Obtained By Addition = "+result);
	}
}

Output:

The Result Obtained By Addition = 30

Explanation

In the above-mentioned Java example program, the inline snippet tag {@InlineSnippet#AddNumbers} is utilized for including the code related to the AddNumbers method in the created Javadoc HTML.

External Snippets

The utilization of inline snippets in Java all the time is not preferred as it is inconvenient. When trying to write the sequence of characters in the comments, the string variable might also contain the */ character sequence.

Utilizing external snippets in situations where the code is accessed by the snippet tag in external file is the solution.

Example 1:

Filename: SnippetTag1.java

// Java program for demonstration of Java Snippet tags
public class SnippetTag1 {
    void display() {
        System.out.println("JAVA SNIPPET TAGS EXAMPLE PROGRAM");
    }
    public static void main(String[] args) {
        SnippetTag1 ob1 = new SnippetTag1();
        ob1.display();
    }
}

Output:

JAVA SNIPPET TAGS EXAMPLE PROGRAM

Example 2:

Filename: ExternalSnippet.java

// Java program for demonstration of features and functionalities of External Snippet in Javadoc
import java.util.*;
import java.io.*;
public class ExternalSnippet{
    /**
     Calculates and returns the Sqaure value of a number.
    parameter num - The number whose Sqaure value will be calculated.
    @return Returns the Sqaure value of the parameter integer value provided.
    */
    public static int sqaureValue(int num) {
		int result;
		result = num * num;
        return result;
    }
	public static void main(String[] args)
	{
		ExternalSnippet ob1 = new ExternalSnippet();
		int result; 
		int num = 10;
		result = sqaureValue(num);
		System.out.println("The Square Value of "+num+" = "+result);
	}
}

Output: