Basic support for JEP 413 (Code Snippets in Java API Documentation)

[gebezs]

JDK 18 delivered the @snippet tag for javadoc: https://openjdk.java.net/jeps/413

Java 18 Snippet documentation: https://docs.oracle.com/en/java/javase/18/code-snippet/index.html

The JEP 413 supports a wide range of options adding code snippets to the javadoc. Supporting everything would be overkill:

local.zip=94123                # @highlight regex="[0-9]+"
System.out.println("Hello World!");  // @link substring="System.out" target="System#out"
System.out.println("Hello World!");  // @replace regex='".*"' replacement="..."
{@snippet file="ShowOptional.java" region="example"}

I think even a basic support would be a great addition.

a, support for inline @snippet

{@snippet :
  if (v.isPresent()) {
     System.out.println("v: " + v.get());
  }
}

b, support for external @snippet (as-is, without region; both file and class)

 {@snippet file=HelloWorld.java}
 {@snippet class=HelloWorld}
 {@snippet file=config.properties}

c, attributes

class — a class containing the content for the snippet file — a file containing the content for the snippet id — an identifier for the snippet, to identify the snippet in the generated documentation lang — the language or format for the snippet

No support for region

d, indentations

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.