[java-inspections] JavadocBlankLines: reports blank lines in Javadoc comments

IDEA-281540

GitOrigin-RevId: 2b1937a1e78a82bcdbfbd54b45a509024bcf1f58

java/java-impl/src/META-INF/JavaPlugin.xml

@@ -1741,6 +1741,9 @@
                      groupKey="group.names.javadoc.issues" groupBundle="messages.InspectionsBundle" enabledByDefault="true" level="WARNING"
                      implementationClass="com.intellij.codeInspection.javaDoc.JavadocDeclarationInspection" alternativeId="javadoc"/>
     <inspectionElementsMerger implementation="com.intellij.codeInspection.javaDoc.JavadocDeclarationMerger" />
+    <localInspection groupPath="Java" language="JAVA" shortName="JavadocBlankLines" bundle="messages.JavaBundle" key="inspection.javadoc.blank.lines.display.name"
+                     groupKey="group.names.javadoc.issues" groupBundle="messages.InspectionsBundle" enabledByDefault="true" level="WARNING"
+                     implementationClass="com.intellij.codeInspection.javaDoc.JavadocBlankLinesInspection" alternativeId="javadoc"/>
     <inspectionElementsMerger implementation="com.intellij.codeInspection.javaDoc.MissingJavadocMerger" />
     <localInspection groupPath="Java" language="JAVA" shortName="ReturnSeparatedFromComputation" bundle="messages.JavaBundle"
                      key="inspection.return.separated.from.computation.name"

java/java-impl/src/com/intellij/codeInspection/javaDoc/JavadocBlankLinesInspection.java

@@ -0,0 +1,80 @@
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
+package com.intellij.codeInspection.javaDoc;
+
+import com.intellij.codeInspection.LocalInspectionTool;
+import com.intellij.codeInspection.LocalQuickFixAndIntentionActionOnPsiElement;
+import com.intellij.codeInspection.ProblemsHolder;
+import com.intellij.java.JavaBundle;
+import com.intellij.openapi.editor.Document;
+import com.intellij.openapi.editor.Editor;
+import com.intellij.openapi.project.Project;
+import com.intellij.openapi.util.TextRange;
+import com.intellij.psi.*;
+import com.intellij.psi.javadoc.PsiDocTag;
+import com.intellij.psi.javadoc.PsiDocToken;
+import com.intellij.psi.javadoc.PsiInlineDocTag;
+import com.intellij.util.ObjectUtils;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+public class JavadocBlankLinesInspection extends LocalInspectionTool {
+  @Override
+  public @NotNull PsiElementVisitor buildVisitor(@NotNull ProblemsHolder holder, boolean isOnTheFly) {
+    return new JavaElementVisitor() {
+      @Override
+      public void visitDocToken(PsiDocToken token) {
+        super.visitDocToken(token);
+        PsiElement nextSibling = token.getNextSibling();
+        if (token.getTokenType() == JavaDocTokenType.DOC_COMMENT_LEADING_ASTERISKS &&
+            token.getPrevSibling() instanceof PsiWhiteSpace &&
+            nextSibling instanceof PsiWhiteSpace && !isBeforeParagraphOrBlockTag(nextSibling)) {
+          holder.registerProblem(token, JavaBundle.message("inspection.javadoc.blank.lines.message"), new InsertParagraphTagFix(token));
+        }
+      }
+    };
+  }
+
+  private static boolean isBeforeParagraphOrBlockTag(PsiElement element) {
+    PsiDocToken maybeLeadingAsterisks = ObjectUtils.tryCast(element.getNextSibling(), PsiDocToken.class);
+    if (maybeLeadingAsterisks == null || maybeLeadingAsterisks.getTokenType() != JavaDocTokenType.DOC_COMMENT_LEADING_ASTERISKS) {
+      return false;
+    }
+    PsiElement nextSibling = maybeLeadingAsterisks.getNextSibling();
+    if (nextSibling == null) return false;
+    return nextSibling.getText().stripLeading().startsWith("<p>") ||
+           isBlockTag(nextSibling) ||
+           isBlockTag(nextSibling.getNextSibling());
+  }
+
+  private static boolean isBlockTag(PsiElement element) {
+    return element instanceof PsiDocTag && !(element instanceof PsiInlineDocTag);
+  }
+
+  private static class InsertParagraphTagFix extends LocalQuickFixAndIntentionActionOnPsiElement {
+    protected InsertParagraphTagFix(@Nullable PsiElement element) {
+      super(element);
+    }
+
+    @Override
+    public void invoke(@NotNull Project project,
+                       @NotNull PsiFile file,
+                       @Nullable Editor editor,
+                       @NotNull PsiElement startElement,
+                       @NotNull PsiElement endElement) {
+      Document document = PsiDocumentManager.getInstance(project).getDocument(file);
+      if (document == null) return;
+      TextRange range = startElement.getTextRange();
+      document.replaceString(range.getStartOffset(), range.getEndOffset(), "* <p>");
+    }
+
+    @Override
+    public @NotNull String getText() {
+      return JavaBundle.message("inspection.javadoc.blank.lines.fix.name");
+    }
+
+    @Override
+    public @NotNull String getFamilyName() {
+      return JavaBundle.message("inspection.javadoc.blank.lines.fix.family.name");
+    }
+  }
+}

java/java-impl/src/inspectionDescriptions/JavadocBlankLines.html

@@ -0,0 +1,36 @@
+<html>
+<body>
+Reports blank lines in Javadoc comments.
+<p>
+  Blank lines in Javadoc may signal an intention split the text to different paragraphs. However, the Javadoc tool and IntelliJ IDEA will
+  ignore them when rendering documentation comments.
+</p>
+<p>
+  The quick-fix suggests to replace the blank line with a paragraph tag (&lt;p&gt;).
+</p>
+<p><b>Example:</b></p>
+<pre><code>
+  class Main {
+    /**
+     * Doesn't do anything.
+     *
+     * Does absolutely nothing
+     */
+    void foo() {}
+  }
+</code></pre>
+<p>After the quick-fix is applied:</p>
+<pre><code>
+  class Main {
+    /**
+     * Doesn't do anything.
+     * &lt;p&gt;
+     * Does absolutely nothing
+     */
+    void foo() {}
+  }
+</code></pre>
+<!-- tooltip end -->
+<p><small>New in 2022.1</small></p>
+</body>
+</html>

java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/afterSimple.java

@@ -0,0 +1,9 @@
+// "Insert <p>" "true"
+class Test {
+  /**
+   * Doesn't do anything.
+   * <p>
+   * Absolutely nothing.
+   */
+  void foo() {}
+}

java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeBlockTag.java

@@ -0,0 +1,11 @@
+// "Insert <p>" "false"
+class Test {
+  /**
+   * Answer to the ultimate question of life, the universe, and everything
+   *<caret>
+   * @return The number 42
+   */
+  int answer() {
+    return 42;
+  }
+}

java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeParagraphTag.java

@@ -0,0 +1,10 @@
+// "Insert <p>" "false"
+class Test {
+  /**
+   * Doesn't do anything.
+   *<caret>
+   * <p>
+   * Absolutely nothing.
+   */
+  void foo() {}
+}

java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeSimple.java

@@ -0,0 +1,9 @@
+// "Insert <p>" "true"
+class Test {
+  /**
+   * Doesn't do anything.
+   *<caret>
+   * Absolutely nothing.
+   */
+  void foo() {}
+}

java/java-tests/testSrc/com/intellij/java/codeInsight/daemon/JavadocBlankLinesInspectionTest.java

@@ -0,0 +1,19 @@
+// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license.
+package com.intellij.java.codeInsight.daemon;
+
+import com.intellij.codeInsight.daemon.quickFix.LightQuickFixParameterizedTestCase;
+import com.intellij.codeInspection.LocalInspectionTool;
+import com.intellij.codeInspection.javaDoc.JavadocBlankLinesInspection;
+import org.jetbrains.annotations.NotNull;
+
+public class JavadocBlankLinesInspectionTest extends LightQuickFixParameterizedTestCase {
+  @Override
+  protected LocalInspectionTool @NotNull [] configureLocalInspectionTools() {
+    return new LocalInspectionTool[]{new JavadocBlankLinesInspection()};
+  }
+
+  @Override
+  protected String getBasePath() {
+    return "/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines";
+  }
+}

java/openapi/resources/messages/JavaBundle.properties

@@ -507,6 +507,10 @@ inspection.javadoc.problem.snippet.tag.is.not.available='@snippet' tag is not av
 inspection.javadoc.problem.see.tag.expecting.ref=Class/method reference, quoted text, or HTML link are expected after @see tag
 inspection.javadoc.problem.wrong.tag=Wrong tag {0}
 inspection.javadoc.ref.display.name=Declaration has problems in Javadoc references
+inspection.javadoc.blank.lines.display.name=Blank lines
+inspection.javadoc.blank.lines.message=Blank line will be ignored
+inspection.javadoc.blank.lines.fix.name=Insert <p>
+inspection.javadoc.blank.lines.fix.family.name=Replace blank lines with <p>
 inspection.javadoc.required.tags.option.title=Required Tags
 inspection.javadoc.throws.or.exception.option=@throws or @exception
 inspection.join.declaration.and.assignment.display.name=Assignment can be joined with declaration