Class JavaDocSnippetExamples

java.lang.Object
net.jrodolfo.java_evolution.java18.javadoc_snippets.JavaDocSnippetExamples
public class JavaDocSnippetExamples extends Object
Demonstrates JavaDoc @snippet, introduced in Java 18.

Before Java 18, JavaDoc examples were commonly written with <pre> blocks. Those blocks displayed code, but the documentation tool could not understand much about the example. The @snippet tag gives examples a first-class structure that JavaDoc can render more clearly.

A compact inline snippet can show a single idea: 

var examples = new JavaDocSnippetExamples();
var title = examples.normalizeTitle("  java   snippets  ");

A longer snippet can show multiple steps and mark a specific region: 

var preview = examples.previewLines(lines, 2);

  • Constructor Details

    • JavaDocSnippetExamples

      public JavaDocSnippetExamples()

  • Method Details

    • normalizeTitle

      public String normalizeTitle(String title)
      Normalizes a short title for display in documentation.

      The snippet is not only formatted text. JavaDoc understands it as a code example and can render it with snippet-aware styling: 

      var examples = new JavaDocSnippetExamples();
var normalized = examples.normalizeTitle("  java   evolution  ");
      Parameters:
      title - title to normalize
      Returns:
      trimmed title with repeated whitespace collapsed and each word capitalized

    • previewLines

      public List<String> previewLines(List<String> lines, int limit)
      Returns a small preview from a larger list.

      Documentation snippets are useful when the reader needs to see a short API interaction without reading a full test class: 

      var examples = new JavaDocSnippetExamples();
var preview = examples.previewLines(List.of("one", "two", "three"), 2);
      Parameters:
      lines - source lines
      limit - maximum number of lines to return
      Returns:
      the first limit lines, or all lines when the list is shorter

    • formatCommand

      public String formatCommand(String command, int port)
      Formats a command shown in documentation.

      Snippets are especially helpful for command-like examples because the source stays readable and the generated JavaDoc stays consistent: 

      var examples = new JavaDocSnippetExamples();
var command = examples.formatCommand("jwebserver", 8000);
      Parameters:
      command - command name
      port - port number
      Returns:
      formatted command