Summary

A method is added to the Reporter interface which allows a diagnostic to be reported at a range of characters within DocTree nodes that wrap a string.

Problem

Currently, the Reporter interface does not provide the resolution to report a diagnostic within a possibly-lengthy string, such as the content of a snippet.

Solution

Add a new method that allows the caller to specify a range of characters and the preferred position for a diagnostic for tree nodes that wrap a simple string.

Specification

/**
 * Prints a diagnostic message related to a position within a range of characters in a tree node.
 *
 * Only kinds of {@code DocTree} that wrap a simple string value are supported as leaf nodes
 * of the given path. This currently includes
 * {@link CommentTree}, {@link DocTypeTree}, {@link ReferenceTree}, and {@link TextTree}.
 *
 * The positions are all 0-based character offsets from the beginning of string.
 * The positions should satisfy the relation {@code start <= pos <= end}.
 *
 * @implSpec
 * This implementation ignores the {@code (start, pos, end)} values and simply calls
 * {@link #print(Diagnostic.Kind, DocTreePath, String) print(kind, path, message)};
 *
 * @param kind    the kind of diagnostic
 * @param path    the path for the tree node
 * @param start   the beginning of the enclosing range
 * @param pos     the position
 * @param end     the end of the enclosing range
 * @param message the message to be printed
 *
 * @throws IllegalArgumentException if {@code start}, {@code pos} and {@code end} do
 *          not form a valid range.
 *
 * @since 18
 */
default void print(Diagnostic.Kind kind, DocTreePath path, int start, int pos, int end, String message) {
    print(kind, path, message);
}