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](https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/lang/String.html#stripIndent()). This means you can control the amount of indentation in the generated output by adjusting the indentation of the final right bracket.