Summary

Amend specification of jdk.javadoc.doclet.Reporter.print(Diagnostic.Kind, DocTreePath, int, int, int, String) that a wrong position may be reported when invoked with a text tree inside a <pre> element that was subject to whitespace normalization.

Problem

To facilitate use of preformatted text in JavaDoc, we plan to strip a single leading space character per line of text inside <pre> elements if the content of a traditional doc comment suggests the leading space is incidental. This causes a potential problem with a Reporter.print method added in JDK 18. The reported position inside the tree content is reduced by 1 per line into the <pre> element. For example, a position in the second line of a <pre> element will be off by -1. There is no risk of an index bounds exceptions as reported positions are always smaller than actual ones.

This only affects positions within TextTree content inside a <pre> element reported by this particular method. It does not affect the position of the TextTree itself, the <pre> element tree, or other trees inside the <pre> element. Whitespace normalization is also performed on the content of {@code} and {@literal} tags, but these tags are not supported by the method in question.

Solution

The method in question was added in support of error reporting for complex taglets like SnippetTaglet and only supports a few specific kinds of DocTree. It is very unlikely to be useful for plain text, which is just passed through without processing. Therefore, adding a note to the method spec describing its limitation seems like a sufficient solution.

Specification

diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java
index 804b621f19c..f2387e7708f 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/doclet/Reporter.java
@@ -94,9 +94,9 @@ public interface Reporter {
      * 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)}.
+     * @implNote
+     * This implementation may report a wrong position for {@code TextTree} content
+     * contained within a {@code <pre>} element subject to whitespace normalization.
      *
      * @param kind    the kind of diagnostic
      * @param path    the path for the tree node
@@ -105,6 +105,8 @@ public interface Reporter {
      * @param end     the end of the enclosing range
      * @param message the message to be printed
      *
+     * @throws IllegalArgumentException if {@code path} points to an unsupported kind
+     *          of {@code DocTree}.
      * @throws IllegalArgumentException if {@code start}, {@code pos} and {@code end} do
      *          not form a valid range.
      *

Note: the removed @implSpec and added @throws tags are to document existing behaviour, which remains unchanged.