Open In App

Java 18 @snippet Tag with Example

Improve
Improve
Like Article
Like
Save
Share
Report

Java 18 adds Code Snippets to the Java API Documentation as a new feature. This presentation demonstrates the @snippet tag, which was added to JavaDoc’s Standard Doclet to make it easier to include example source code in the API documentation. API documentation writers frequently include snippets of source code in the documentation comments. For short or one-line examples, they use the syntax @code, whereas, for lengthier examples, they use <pre>@code…/pre>. The @snippet tag is an alternative for those methods that are easier to use, offer greater strength, and are more adaptable. In documentation comments, it is customary to begin lines with whitespace and an asterisk, as demonstrated in the following example:

/**
* The main program.
*
* <pre>{@code
*   System.out.println(“Hello Geeks!”);
* }</pre>
*/
public static void main(String[] args) {
  …
}

The body of the @code tag will be rendered into HTML code by the javadoc tool. This technique has some drawbacks, including the inability to highlight syntax, contain HTML markups, handle issues with indentation, etc. To give developers additional flexibility when inserting source code snippets in the documentation, this JEP introduces the @snippet tag.

Inline snippets

A text fragment, such as source code or another type of structured text, can be enclosed using the simplest form of the syntax, “@snippet…”

/**
* The following code shows how to use {@code Optional.isPresent}:
* {@snippet :
* if (optionalObj.isPresent()) {
*     System.out.println(“optionalObj: ” + optionalObj.get());
* }
* }
*/

The generated documentation renders the text of the {@snippet …} tags as HTML code. Special characters such as < and > do not need to be escaped with HTML entities.

External snippets

Utilizing inline snippets is not always convenient or even feasible. Various portions of a single example might be shown, or you could include /*… Because these comments do not nest and the trailing */ would end the enclosing comment, they cannot be rendered in an inline snippet. When trying to write the character sequence in a conventional comment, the character sequence */ may also appear in string literals, such as glob patterns or regular expressions, with the same problems. Use external snippets, where the snippet tag accesses code in an external file, to remedy this.

Java




public class SnippetExample {
     /**
      * The following code shows how to use {@code Optional.isPresent}:
      * {@snippet file="ShowOptional.java" region="sample"}
      */
     void mock() {
       System.out.println("Hello Geeksforgeeks !!!);
     }
 }


Java




public class ShowOptional {
    void show(Optional<String> optionalObj) {
        // @start region="sample"
        if (optionalObj.isPresent()) {
            System.out.println("optionalObj: " + optionalObj.get());
        }
        // @end
    }
}


The ShowExample.java documentation will include the contents of the requested @start and @end sections.

if (optionalObj.isPresent()) {
           System.out.println(“optionalObj: ” + optionalObj.get());
       }



Last Updated : 24 Dec, 2022
Like Article
Save Article
Previous
Next
Share your thoughts in the comments
Similar Reads