8352249: Remove incidental whitespace in traditional doc comments

Reviewed-by: liach

Author: hns

src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -1070,6 +1070,11 @@ public String getText() {
                 return "";
             }
 
+            @Override
+            public Comment stripIndent() {
+                return this;
+            }
+
             @Override
             public JCDiagnostic.DiagnosticPosition getPos() {
                 return null;

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -158,7 +158,7 @@ public DocCommentParser(ParserFactory fac, DiagnosticSource diagSource,
         this.fac = fac;
         this.diags = fac.log.diags;
         this.diagSource = diagSource;
-        this.comment = comment;
+        this.comment = comment.stripIndent();
         names = fac.names;
         this.isHtmlFile = isHtmlFile;
         textKind = isHtmlFile ? DocTree.Kind.TEXT : getTextKind(comment);

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java

@@ -1265,6 +1265,21 @@ public String getText() {
             return null;
         }
 
+        /**
+         * Return a version of this comment with incidental whitespace removed,
+         * or this comment if the operation is not supported.
+         *
+         * @return comment with removed whitespace or this comment
+         */
+        public Comment stripIndent() {
+            return this;
+        }
+
+        /**
+         * Return the diagnostic position of this comment.
+         *
+         * @return diagnostic position
+         */
         public DiagnosticPosition getPos() {
             return pos;
         }

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavadocTokenizer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2021, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -27,11 +27,11 @@
 
 import com.sun.tools.javac.parser.Tokens.Comment;
 import com.sun.tools.javac.parser.Tokens.Comment.CommentStyle;
-import com.sun.tools.javac.util.*;
+import com.sun.tools.javac.util.JCDiagnostic;
+import com.sun.tools.javac.util.Position;
 
 import java.nio.CharBuffer;
 import java.util.Arrays;
-import java.util.regex.Pattern;
 
 /**
  * An extension to the base lexical analyzer (JavaTokenizer) that
@@ -170,6 +170,11 @@ protected void scanDocComment() {
                 offsetMap.trim();
             }
         }
+
+        @Override
+        public Comment stripIndent() {
+            return StrippedComment.of(this);
+        }
     }
 
     /**
@@ -354,4 +359,154 @@ int getSourcePos(int pos) {
             return map[startScaled + POS_OFFSET] + (pos - map[startScaled + SB_OFFSET]);
         }
     }
+
+    /**
+     * A Comment derived from a JavadocComment with leading whitespace removed from all lines.
+     * A new OffsetMap is used in combination with the OffsetMap of the original comment to
+     * translate comment locations to positions in the source file.
+     *
+     * Note: This class assumes new lines are encoded as {@code '\n'}, which is the case
+     * for comments created by {@code JavadocTokenizer}.
+     */
+    static class StrippedComment implements Comment {
+        String text;
+        final OffsetMap strippedMap;
+        final OffsetMap sourceMap;
+        // Copy these fields to not hold a reference to the original comment with its text
+        final JCDiagnostic.DiagnosticPosition diagPos;
+        final CommentStyle style;
+        final boolean deprecated;
+
+        /**
+         * Returns a stripped version of the comment, or the comment itself if there is no
+         * whitespace that can be stripped.
+         *
+         * @param comment the original comment
+         * @return stripped or original comment
+         */
+        static Comment of(JavadocComment comment) {
+            if (comment.getStyle() != CommentStyle.JAVADOC_BLOCK) {
+                return comment;
+            }
+            int indent = getIndent(comment);
+            return indent > 0 ? new StrippedComment(comment, indent) : comment;
+        }
+
+        private StrippedComment(JavadocComment comment, int indent) {
+            this.diagPos = comment.getPos();
+            this.style = comment.getStyle();
+            this.deprecated = comment.isDeprecated();
+            this.strippedMap = new OffsetMap();
+            this.sourceMap = comment.offsetMap;
+            stripComment(comment, indent);
+        }
+
+        /**
+         * Determines the number of leading whitespace characters that can be removed from
+         * all non-blank lines of the original comment.
+         *
+         * @param comment the original comment
+         * @return number of leading whitespace characters that can be reomved
+         */
+        static int getIndent(Comment comment) {
+            String txt = comment.getText();
+            int len = txt.length();
+            int indent = Integer.MAX_VALUE;
+
+            for (int i = 0; i < len; ) {
+                int next;
+                boolean inIndent = true;
+                for (next = i; next < len && txt.charAt(next) != '\n'; next++) {
+                    if (inIndent && !Character.isWhitespace(txt.charAt(next))) {
+                        indent = Math.min(indent, next - i);
+                        inIndent = false;
+                    }
+                }
+                i = next + 1;
+            }
+
+            return indent == Integer.MAX_VALUE ? 0 : indent;
+        }
+
+        /**
+         * Strips {@code indent} whitespace characters from every line of the original comment
+         * and initializes an OffsetMap to translate positions to the original comment's OffsetMap.
+         * This method does not distinguish between blank and non-blank lines except for the fact
+         * that blank lines are not required to contain the number of leading whitespace indicated
+         * by {@indent}.
+         *
+         * @param comment the original comment
+         * @param indent number of whitespace characters to remove from each non-blank line
+         */
+        private void stripComment(JavadocComment comment, int indent) {
+            String txt = comment.getText();
+            int len = txt.length();
+            StringBuilder sb = new StringBuilder(len);
+
+            for (int i = 0; i < len; ) {
+                int startOfLine = i;
+                // Advance till start of stripped line, or \n if line is blank
+                while (startOfLine < len
+                        && startOfLine < i + indent
+                        && txt.charAt(startOfLine) != '\n') {
+                    assert(Character.isWhitespace(txt.charAt(startOfLine)));
+                    startOfLine++;
+                }
+                if (startOfLine == len) {
+                    break;
+                }
+
+                // Copy stripped line (terminated by \n or end of input)
+                i = startOfLine + 1;
+                while (i < len && txt.charAt(i - 1) != '\n') {
+                    i++;
+                }
+                // Add new offset if necessary
+                strippedMap.add(sb.length(), startOfLine);
+                sb.append(txt, startOfLine, i);
+            }
+
+            text = sb.toString();
+            strippedMap.trim();
+        }
+
+        @Override
+        public String getText() {
+            return text;
+        }
+
+        @Override
+        public Comment stripIndent() {
+            return this;
+        }
+
+        @Override
+        public int getSourcePos(int pos) {
+            if (pos == Position.NOPOS) {
+                return Position.NOPOS;
+            }
+
+            if (pos < 0 || pos > text.length()) {
+                throw new StringIndexOutOfBoundsException(String.valueOf(pos));
+            }
+
+            return sourceMap.getSourcePos(strippedMap.getSourcePos(pos));
+        }
+
+        @Override
+        public JCDiagnostic.DiagnosticPosition getPos() {
+            return diagPos;
+        }
+
+        @Override
+        public CommentStyle getStyle() {
+            return style;
+        }
+
+        @Override
+        public boolean isDeprecated() {
+            return deprecated;
+        }
+    }
+
 }

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Tokens.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -281,6 +281,7 @@ enum CommentStyle {
         }
 
         String getText();
+        Comment stripIndent();
         JCDiagnostic.DiagnosticPosition getPos();
         int getSourcePos(int index);
         CommentStyle getStyle();

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocPretty.java

@@ -345,7 +345,7 @@ public Void visitLiteral(LiteralTree node, Void p) {
             print('{');
             printTagName(node);
             String body = node.getBody().getBody();
-            if (!body.isEmpty() && !Character.isWhitespace(body.charAt(0))) {
+            if (!body.isEmpty() && body.charAt(0) != '\n') {
                 print(' ');
             }
             print(node.getBody());

src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2011, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2011, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -236,6 +236,9 @@ public String getText() {
                 throw new UnsupportedOperationException(getClass() + ".getText");
             }
 
+            @Override
+            public Comment stripIndent() { return this; }
+
             @Override
             public CommentStyle getStyle() {
                 throw new UnsupportedOperationException(getClass() + ".getStyle");

test/langtools/jdk/javadoc/doclet/testAutoHeaderId/TestAutoHeaderId.java

@@ -133,8 +133,8 @@ private void checkIds() {
                     """,
                 """
                     <h2 id="3-0-multi-line-heading-with-extra-whitespace-heading"> 3.0 Multi-line
-                           heading   with extra
-                                     whitespace</h2>""");
+                          heading   with extra
+                                    whitespace</h2>""");
     }
 
     private void checkSearchIndex() {

test/langtools/jdk/javadoc/doclet/testBreakIterator/TestBreakIterator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2002, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2002, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -70,16 +70,16 @@ public void test() {
         checkOutput("pkg/BreakIteratorTest.html", true,
                 """
                     <div class="block">with an anchor for the
-                     <a href="../index-all.html">top level index</a>.</div>""");
+                    <a href="../index-all.html">top level index</a>.</div>""");
 
         checkOutput("pkg/BreakIteratorTest.html", true,
                 """
                     <div class="block">A constant indicating that the keyLocation is indeterminate
-                     or not relevant.</div>""");
+                    or not relevant.</div>""");
 
         checkOutput("pkg/BreakIteratorTest.html", true,
                 """
                     <div class="block">Inline tags <i><a href="../index-all.html">extending
-                     beyond the first sentence.</a></i></div>""");
+                    beyond the first sentence.</a></i></div>""");
     }
 }

test/langtools/jdk/javadoc/doclet/testCRLineSeparator/TestCRLineSeparator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2004, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2004, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -53,7 +53,7 @@ public void test() throws IOException {
 
         checkOutput("pkg/MyClass.html", true,
                 "Line 1\n"
-                + " Line 2");
+                + "Line 2");
     }
 
     // recursively copy files from fromDir to toDir, replacing newlines