From b20808f9b0522bfb48800e11d023dea8014641b4 Mon Sep 17 00:00:00 2001 From: "Andrey.Cherkasov" Date: Fri, 18 Feb 2022 14:44:39 +0300 Subject: [PATCH] [java-inspections] JavadocBlankLines: reports blank lines in Javadoc comments IDEA-281540 GitOrigin-RevId: 2b1937a1e78a82bcdbfbd54b45a509024bcf1f58 --- java/java-impl/src/META-INF/JavaPlugin.xml | 3 + .../javaDoc/JavadocBlankLinesInspection.java | 80 +++++++++++++++++++ .../JavadocBlankLines.html | 36 +++++++++ .../javadocBlankLines/afterSimple.java | 9 +++ .../javadocBlankLines/beforeBlockTag.java | 11 +++ .../javadocBlankLines/beforeParagraphTag.java | 10 +++ .../javadocBlankLines/beforeSimple.java | 9 +++ .../JavadocBlankLinesInspectionTest.java | 19 +++++ .../resources/messages/JavaBundle.properties | 4 + 9 files changed, 181 insertions(+) create mode 100644 java/java-impl/src/com/intellij/codeInspection/javaDoc/JavadocBlankLinesInspection.java create mode 100644 java/java-impl/src/inspectionDescriptions/JavadocBlankLines.html create mode 100644 java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/afterSimple.java create mode 100644 java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeBlockTag.java create mode 100644 java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeParagraphTag.java create mode 100644 java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeSimple.java create mode 100644 java/java-tests/testSrc/com/intellij/java/codeInsight/daemon/JavadocBlankLinesInspectionTest.java diff --git a/java/java-impl/src/META-INF/JavaPlugin.xml b/java/java-impl/src/META-INF/JavaPlugin.xml index 4671eae006a6..31bad1c2cda6 100644 --- a/java/java-impl/src/META-INF/JavaPlugin.xml +++ b/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"/> + ") || + 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(), "*

"); + } + + @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"); + } + } +} diff --git a/java/java-impl/src/inspectionDescriptions/JavadocBlankLines.html b/java/java-impl/src/inspectionDescriptions/JavadocBlankLines.html new file mode 100644 index 000000000000..c842b177e46a --- /dev/null +++ b/java/java-impl/src/inspectionDescriptions/JavadocBlankLines.html @@ -0,0 +1,36 @@ + + +Reports blank lines in Javadoc comments. +

+ 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. +

+

+ The quick-fix suggests to replace the blank line with a paragraph tag (<p>). +

+

Example:

+

+  class Main {
+    /**
+     * Doesn't do anything.
+     *
+     * Does absolutely nothing
+     */
+    void foo() {}
+  }
+
+

After the quick-fix is applied:

+

+  class Main {
+    /**
+     * Doesn't do anything.
+     * <p>
+     * Does absolutely nothing
+     */
+    void foo() {}
+  }
+
+ +

New in 2022.1

+ + diff --git a/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/afterSimple.java b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/afterSimple.java new file mode 100644 index 000000000000..729867cd9e7e --- /dev/null +++ b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/afterSimple.java @@ -0,0 +1,9 @@ +// "Insert

" "true" +class Test { + /** + * Doesn't do anything. + *

+ * Absolutely nothing. + */ + void foo() {} +} diff --git a/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeBlockTag.java b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeBlockTag.java new file mode 100644 index 000000000000..f526cf6b2f91 --- /dev/null +++ b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeBlockTag.java @@ -0,0 +1,11 @@ +// "Insert

" "false" +class Test { + /** + * Answer to the ultimate question of life, the universe, and everything + * + * @return The number 42 + */ + int answer() { + return 42; + } +} diff --git a/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeParagraphTag.java b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeParagraphTag.java new file mode 100644 index 000000000000..2543ae1a3f23 --- /dev/null +++ b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeParagraphTag.java @@ -0,0 +1,10 @@ +// "Insert

" "false" +class Test { + /** + * Doesn't do anything. + * + *

+ * Absolutely nothing. + */ + void foo() {} +} diff --git a/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeSimple.java b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeSimple.java new file mode 100644 index 000000000000..2afe4477f929 --- /dev/null +++ b/java/java-tests/testData/codeInsight/daemonCodeAnalyzer/quickFix/javadocBlankLines/beforeSimple.java @@ -0,0 +1,9 @@ +// "Insert

" "true" +class Test { + /** + * Doesn't do anything. + * + * Absolutely nothing. + */ + void foo() {} +} diff --git a/java/java-tests/testSrc/com/intellij/java/codeInsight/daemon/JavadocBlankLinesInspectionTest.java b/java/java-tests/testSrc/com/intellij/java/codeInsight/daemon/JavadocBlankLinesInspectionTest.java new file mode 100644 index 000000000000..0980110fbe85 --- /dev/null +++ b/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"; + } +} diff --git a/java/openapi/resources/messages/JavaBundle.properties b/java/openapi/resources/messages/JavaBundle.properties index 1dc9be06eb9c..a9f0a9f79a04 100644 --- a/java/openapi/resources/messages/JavaBundle.properties +++ b/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

+inspection.javadoc.blank.lines.fix.family.name=Replace blank lines with

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