Scribd
Upload
8 views

3 Snippets

JEP 413 introduces a new JavaDoc feature, the {@snippet ...} tag, to enhance the inclusion of code examples in API documentation for JDK 18 and later. This guide outlines the usage of the snippet feature, covering topics such as inline snippets, indentation, attributes, and limitations. It provides practical examples and explanations to help authors effectively implement this feature in their documentation.

Uploaded by

towocow500
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
8 views

3 Snippets

JEP 413 introduces a new JavaDoc feature, the {@snippet ...} tag, to enhance the inclusion of code examples in API documentation for JDK 18 and later. This guide outlines the usage of the snippet feature, covering topics such as inline snippets, indentation, attributes, and limitations. It provides practical examples and explanations to help authors effectively implement this feature in their documentation.

Uploaded by

towocow500
Copyright
© © All Rights Reserved
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 3

3 Snippets

JEP 413 adds a JavaDoc feature to improve support for code examples in API documentation to
JDK 18 and later. This guide provides information on how to use the feature, using a series of
simple examples.

Topics
 Introduction
 Inline Snippets
 Indentation
 Attributes
 Markup Comments
 Regions
 External Snippets
 Limitations of End-of-Line Comments
 Hybrid Snippets
 Testing Snippets

Introduction
Authors of API documentation frequently include fragments of source code in documentation
comments, using constructs like {@code ...} for short or one-line examples,
or <pre>{@code ...}</pre> for longer examples. The {@snippet ...} tag is a replacement for
those techniques that is more convenient to use, and which provides more power and flexibility.

It is common practice in documentation comments to prefix lines with whitespace characters and
an asterisk, as shown in this example:

Copy
/**
* The main program.
*
* The code calls the following statement:
* <pre>{@code
* System.out.println("Hello, World!");
* }</pre>
*/
public static void main(String... args) {
...
}
In the examples that follow, snippet tags and related files are displayed in indented blocks with a
border. For simplicity and clarity, snippet tags are shown without the typographic decoration of the
enclosing comment. (It is neither required nor incorrect to use such decoration in actual use.)
Blocks without a border are used to display the corresponding output generated by the Standard
Doclet. The output for all snippets includes a Copy to Clipboard button in the upper-left corner.

Inline Snippets
In its simplest form, {@snippet ...} can be used to enclose a fragment of text, such as source
code or any other form of structured text.
Copy
{@snippet :
public static void main(String... args) {
System.out.println("Hello, World!");
}
}
This will appear in the generated output as follows:

Copy
public static void main(String... args) {
System.out.println("Hello, World!");
}
Apart from some inherent limitations, there are no restrictions on the content of a snippet. The
limitations are a result of embedding the snippet within a documentation comment. The limitations
for an inline snippet are:

 the content may not contain the character pair */, because that would terminate the
enclosing comment
 Unicode escape sequences (\uNNNN) will be interpreted while parsing the source code,
and so it is not possible to distinguish between the presence of a character and the
equivalent Unicode escape sequence, and
 any curly bracket characters ({} ) must be "balanced", implying an equal number of
appropriately nested left curly bracket and right curly bracket characters, so that the
closing curly bracket of the @snippet tag can be determined.

Indentation
The content of an inline snippet is the text between the newline after the initial colon (:) and the
final right curly bracket (}). Incidental white space is removed from the content in the same way as
with String.stripIndent. This means you can control the amount of indentation in the
generated output by adjusting the indentation of the final right bracket.

In this example, the snippet tag is the same as in the previous example, except that the indentation
of the final right curly bracket is increased, to eliminate the indentation in the generated output.

Copy
{@snippet :
public static void main(String... args) {
System.out.println("Hello, World!");
}
}
This will appear in the generated output as follows:

Copy
public static void main(String... args) {
System.out.println("Hello, World!");
}

Attributes
A snippet may have attributes, which are name=value pairs. Values can be quoted with single-
quote (') characters or double-quote (") character. Simple values, such as identifiers or numbers
need not be quoted. Note: escape sequences are not supported in attribute values.
The lang attribute is used to identify the language of the snippet text, and to infer the kind of line
comment or end-of-line comment that may be supported in that language. The Standard Doclet
recognizes java and properties as supported values. The value of the attribute is also passed
through to the generated HTML. The attribute may be used by other tools that can be used to
analyze the snippet text.

Copy
{@snippet lang="java" :
public static void main(String... args) {
System.out.println("Hello, World!");
}
}
Snippets often contain Java source code, but are not limited to that. Snippets may contain other
forms of structured text, such as the resources that can appear in a "properties" file.

You might also like