Java_18_Features - Code Snippets in Java API Doc

Java 18 Introduces the @snippet tag for JavaDoc’s Standard Doclet to simplify the inclusion of example source code in API documentation that will be displayed in the generated document.

This features can be used by API developers to include sample code in the documentation and developers can see the usage of API within the documentation instead of shuffling between API and examples.

This feature facilitates the validation and formatting of source code fragments in API documentation. 

Although correctness is ultimately the responsibility of the author, enhanced support in javadoc and related tools can make it easier to achieve, enabling modern styling, such as syntax highlighting, as well as the automatic linkage of names to declarations, and enabling better Integrated Development Environment (IDE) support for creating and editing snippets.

There are 2 types of snippets

• Inline snippets – code snippet is contained in the tag itself
• external snippets – code snippet is read from another source file

Inline snippets

An inline snippet contains the content of the snippet within the tag itself.

Here is an example of an inline snippet:

The content of the snippet, which is included in the generated documentation, is the text between the newline after the colon (:) and the closing curly brace (}).

public class FileWriterExample {
    public static void main(String[] args) throws IOException {
        FileWriterExample fw = new FileWriterExample();
        String str = "Java18";
        String fileName = "test.txt";
        fw.writeToFile(str,fileName);
    }

    /**
     *
     * The following code shows how to use {@code writeToFile(String str,String fileName) }:
     * {@snippet :
     *      public void writeToFile(String str,String fileName) throws IOException {
     *         FileWriter fw = new FileWriter(fileName);
     *         fw.write(str);
     *         fw.flush();
     *     }
     *
     * }
     * @param str - text to be written to file
     * @param fileName - name of the file
     * @throws IOException
     *
     */
    public void writeToFile(String str,String fileName) throws IOException {

        FileWriter fw = new FileWriter(fileName);
        fw.write(str);
        fw.flush();
    }
}

If you generate javadoc for above class, you can see the sample code in documentation itself.

There are 3 limitations on the content of inline snippets

1. An inline snippet cannot use  block comments (/* ... */) comments. */ would terminate the enclosing documentation comment
2. The content of an inline snippet can only contain balanced pairs of curly-brace characters.
3. Can not be shared with elsewhere in the documentation

Inline snippets are suitable for following conditions

• Sample code is small
• If the sample code need not shared with other parts of documentation

External snippets

An external snippet refers to a separate file that contains the content of the snippet.

In an external snippet the colon, newline, and subsequent content can be omitted.

Following code is example for an external snippet in java doc

package dev.fullstack.test;

import java.io.FileWriter;
import java.io.IOException;

public class ExternalCodeSnippets {
    public static void main(String[] args) throws IOException {
        FileWriterExample fw = new FileWriterExample();
        String str = "Java18";
        String fileName = "test.txt";
        fw.writeToFile(str,fileName);
    }

    /**
     *
     * The following code shows how to use {@code writeToFile(String str,String fileName) }:
     * {@snippet file="ShowFileWriter.java" region="example"}
     * @param str - text to be written to file
     * @param fileName - name of the file
     * @throws IOException
     *
     */
    public void writeToFile(String str,String fileName) throws IOException {

        FileWriter fw = new FileWriter(fileName);
        fw.write(str);
        fw.flush();
    }

    /**
     *
     * The following code shows how to use {@code writeToFile(String str,String fileName) }:
     * {@snippet class="ShowFileWriter" region="example2"}
     * @param str - text to be written to file
     * @param fileName - name of the file
     * @throws IOException
     *
     */
    public void writeToFile2(String str,String fileName) throws IOException {

        FileWriter fw = new FileWriter(fileName);
        fw.write(str);
        fw.flush();
    }
}

public class ShowFileWriter {
    // @start region="example2"
    void writeToFile(String str,String fileName) throws IOException {
        // @start region="example"
        FileWriter fw = new FileWriter(fileName);
        fw.write(str);
        fw.flush();
        // @end
    }
    // @end
}

You can refer to the external snippet using class or file attribute.

If are using file attribute , you have to mention the .java extension, while using class attribute you should omit the extention.

The @start and @end tags in ShowFileWriter.java define the bounds of the region.

You can define multiple regions with in the snippet file and refer them from source API files.

External snippet files can be placed either in a snippet-files subdirectory of the package containing the snippet tag, or in a completely separate directory.

Note

some build systems may (incorrectly) treat files in the snippet-files directory as part of the enclosing package hierarchy, even though snippet-files is not a valid Java identifier and cannot be part of a Java package name. The local snippet-files directory cannot be used in these cases.

If you are placing snippet files outside src directory there is no restriction on the folder name.

when running javadoc command you need to specify the absolute path of snippet file using --snippet-path option.

javadoc --snippet-path=D:\IdeaProjects\Java18Features/snippet-src/src ....

Below you can see the generated java documentation.The snippet code generated based on the regions.

Advantages

1. You can separate code and java documentation
2. Can be written as Text files or Class files
3. Can be shared between multiple files