From 5fabc33985349c65726a9f5d99d70aa4437f4024 Mon Sep 17 00:00:00 2001 From: Anna Kozlova Date: Tue, 8 Feb 2022 23:00:08 +0100 Subject: [PATCH] [javadoc] replace inferred/external explanation section with external links to help (IDEA-179266) GitOrigin-RevId: 1e9a12f907fe6861eb0ad3ee975a11a34af4d75c --- .../javadoc/AnnotationDocGenerator.java | 22 +++++--- .../javadoc/JavaDocInfoGenerator.java | 11 ---- .../javadoc/NonCodeAnnotationGenerator.java | 53 +------------------ ...ssWithReferencesToClassesFromJavaLang.html | 4 +- ...ntationForUncheckedExceptionsInSupers.html | 4 +- .../codeInsight/javadocIG/enumValueOf.html | 4 +- .../javadocIG/inheritedParameter.html | 2 +- .../javadocIG/lambdaParameter.html | 2 +- .../javadocIG/syntheticEnumValues.html | 4 +- .../BytecodeAnalysisIntegrationTest.java | 6 +-- .../resources/messages/JavaBundle.properties | 3 -- .../groovy/GroovyDocumentationTest.groovy | 4 +- 12 files changed, 31 insertions(+), 88 deletions(-) diff --git a/java/java-impl/src/com/intellij/codeInsight/javadoc/AnnotationDocGenerator.java b/java/java-impl/src/com/intellij/codeInsight/javadoc/AnnotationDocGenerator.java index 7b6ebdb113ae..4247f5861817 100644 --- a/java/java-impl/src/com/intellij/codeInsight/javadoc/AnnotationDocGenerator.java +++ b/java/java-impl/src/com/intellij/codeInsight/javadoc/AnnotationDocGenerator.java @@ -1,16 +1,18 @@ -// Copyright 2000-2021 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. +// 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.codeInsight.javadoc; import com.intellij.codeInsight.AnnotationTargetUtil; import com.intellij.codeInsight.AnnotationUtil; import com.intellij.ide.highlighter.JavaHighlightingColors; import com.intellij.lang.Language; +import com.intellij.lang.documentation.DocumentationMarkup; import com.intellij.lang.documentation.DocumentationSettings; import com.intellij.openapi.diagnostic.Logger; import com.intellij.openapi.editor.colors.TextAttributesKey; import com.intellij.openapi.editor.richcopy.HtmlSyntaxInfoUtil; import com.intellij.openapi.project.IndexNotReadyException; import com.intellij.openapi.project.Project; +import com.intellij.openapi.util.text.HtmlChunk; import com.intellij.openapi.util.text.StringUtil; import com.intellij.psi.*; import com.intellij.util.ObjectUtils; @@ -112,19 +114,20 @@ public final class AnnotationDocGenerator { AnnotationFormat format, boolean generateLink, boolean isForRenderedDoc, - boolean doSyntaxHighlighting - ) { + boolean doSyntaxHighlighting) { String qualifiedName = myAnnotation.getQualifiedName(); PsiClassType type = myTargetClass != null && qualifiedName != null && JavaDocUtil.findReferenceTarget(myContext.getManager(), qualifiedName, myContext) != null ? JavaPsiFacade.getElementFactory(myContext.getProject()).createType(myTargetClass, PsiSubstitutor.EMPTY) : null; - boolean red = type == null && !myResolveNotPossible && !isInferred() && !isExternal(); + boolean isInferred = isInferred(); + boolean red = type == null && !myResolveNotPossible && !isInferred && !isExternal(); - boolean highlightNonCodeAnnotations = format == AnnotationFormat.ToolTip && (isInferred() || isExternal()); + boolean isNonCodeAnnotation = isInferred || isExternal(); + boolean highlightNonCodeAnnotations = format == AnnotationFormat.ToolTip && isNonCodeAnnotation; if (highlightNonCodeAnnotations) buffer.append(""); - if (isInferred()) buffer.append(""); + if (isInferred) buffer.append(""); if (red) buffer.append(""); boolean forceShortNames = format != AnnotationFormat.JavaDocComplete; @@ -152,8 +155,13 @@ public final class AnnotationDocGenerator { if (red) buffer.append(""); generateAnnotationAttributes(buffer, generateLink, isForRenderedDoc, doSyntaxHighlighting); - if (isInferred()) buffer.append(""); + if (isInferred) buffer.append(""); if (highlightNonCodeAnnotations) buffer.append(""); + if (generateLink && isNonCodeAnnotation && !isForRenderedDoc) { + HtmlChunk.link(isInferred ? "https://www.jetbrains.com/help/idea/annotating-source-code.html#bundled-annotations" + : "https://www.jetbrains.com/help/idea/external-annotations.html", + DocumentationMarkup.EXTERNAL_LINK_ICON).appendTo(buffer); + } } private void generateAnnotationAttributes( diff --git a/java/java-impl/src/com/intellij/codeInsight/javadoc/JavaDocInfoGenerator.java b/java/java-impl/src/com/intellij/codeInsight/javadoc/JavaDocInfoGenerator.java index 3a667635cdd0..b9397db3c9f0 100644 --- a/java/java-impl/src/com/intellij/codeInsight/javadoc/JavaDocInfoGenerator.java +++ b/java/java-impl/src/com/intellij/codeInsight/javadoc/JavaDocInfoGenerator.java @@ -718,9 +718,6 @@ public class JavaDocInfoGenerator { buffer.append(DocumentationMarkup.SECTIONS_START); } - if (!isRendered()) { - new NonCodeAnnotationGenerator(aClass, buffer).explainAnnotations(isRendered(), doHighlightSignatures()); - } buffer.append(DocumentationMarkup.SECTIONS_END); } @@ -926,7 +923,6 @@ public class JavaDocInfoGenerator { if (!isRendered()) { JavaDocColorUtil.appendColorPreview(field, buffer); - new NonCodeAnnotationGenerator(field, buffer).explainAnnotations(isRendered(), doHighlightSignatures()); } buffer.append(DocumentationMarkup.SECTIONS_END); @@ -1267,9 +1263,6 @@ public class JavaDocInfoGenerator { } } - buffer.append(DocumentationMarkup.SECTIONS_START); - new NonCodeAnnotationGenerator(parameter, buffer).explainAnnotations(isRendered(), doHighlightSignatures()); - buffer.append(DocumentationMarkup.SECTIONS_END); } public String generateMethodParameterJavaDoc() { @@ -1400,10 +1393,6 @@ public class JavaDocInfoGenerator { generateUnknownTagsSections(buffer, comment); } - if (!isRendered()) { - new NonCodeAnnotationGenerator(method, buffer).explainAnnotations(isRendered(), doHighlightSignatures()); - } - buffer.append(DocumentationMarkup.SECTIONS_END); } diff --git a/java/java-impl/src/com/intellij/codeInsight/javadoc/NonCodeAnnotationGenerator.java b/java/java-impl/src/com/intellij/codeInsight/javadoc/NonCodeAnnotationGenerator.java index 49171289d552..30e67d28e864 100644 --- a/java/java-impl/src/com/intellij/codeInsight/javadoc/NonCodeAnnotationGenerator.java +++ b/java/java-impl/src/com/intellij/codeInsight/javadoc/NonCodeAnnotationGenerator.java @@ -1,13 +1,9 @@ -// Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. +// 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.codeInsight.javadoc; import com.intellij.java.JavaBundle; -import com.intellij.lang.documentation.DocumentationMarkup; -import com.intellij.openapi.util.text.StringUtil; import com.intellij.psi.PsiMethod; import com.intellij.psi.PsiModifierListOwner; -import com.intellij.psi.PsiNamedElement; -import com.intellij.psi.util.JavaElementKind; import com.intellij.util.containers.ContainerUtil; import com.intellij.util.containers.MultiMap; import org.jetbrains.annotations.Nls; @@ -19,35 +15,6 @@ import java.util.Collections; import java.util.List; public class NonCodeAnnotationGenerator { - private final PsiModifierListOwner myOwner; - private final StringBuilder myOutput; - - NonCodeAnnotationGenerator(@NotNull PsiModifierListOwner owner, StringBuilder output) { - myOwner = owner; - myOutput = output; - } - - void explainAnnotations(boolean isForRenderedFoc, boolean doSyntaxHighlighting) { - MultiMap generators = getSignatureNonCodeAnnotations(myOwner); - if (generators.isEmpty()) return; - - myOutput.append(DocumentationMarkup.SECTION_HEADER_START); - myOutput.append(getNonCodeHeader(generators.values())).append(":"); - myOutput.append(DocumentationMarkup.SECTION_SEPARATOR); - - generators.keySet().forEach(owner -> { - myOutput.append("

"); - if (generators.size() > 1) { - myOutput.append(getKind(owner)).append(" ").append(((PsiNamedElement)owner).getName()).append(": ").append("
"); - } - List annotations = new ArrayList<>(generators.get(owner)); - for (int i = 0; i < annotations.size(); i++) { - if (i > 0) myOutput.append("
"); - annotations.get(i).generateAnnotation(myOutput, AnnotationFormat.JavaDocComplete, true, isForRenderedFoc, doSyntaxHighlighting); - } - }); - myOutput.append(DocumentationMarkup.SECTION_END); - } @NotNull public static MultiMap getSignatureNonCodeAnnotations(PsiModifierListOwner owner) { @@ -72,20 +39,6 @@ public class NonCodeAnnotationGenerator { return allOwners; } - @NotNull - public static @Nls String getNonCodeHeader(Collection values) { - boolean hasExternal = values.stream().anyMatch(AnnotationDocGenerator::isExternal); - boolean hasInferred = values.stream().anyMatch(AnnotationDocGenerator::isInferred); - - if (hasExternal && hasInferred) { - return JavaBundle.message("non.code.annotations.explanation.external.and.inferred"); - } - if (hasExternal) { - return JavaBundle.message("non.code.annotations.explanation.external"); - } - return JavaBundle.message("non.code.annotations.explanation.inferred"); - } - @NotNull public static @Nls String getNonCodeHeaderAvalable(Collection values) { boolean hasExternal = values.stream().anyMatch(AnnotationDocGenerator::isExternal); @@ -99,8 +52,4 @@ public class NonCodeAnnotationGenerator { } return JavaBundle.message("non.code.annotations.explanation.inferred.available"); } - - private static String getKind(PsiModifierListOwner owner) { - return StringUtil.capitalize(JavaElementKind.fromElement(owner).subject()); - } } diff --git a/java/java-tests/testData/codeInsight/javadocIG/documentationForJdkClassWithReferencesToClassesFromJavaLang.html b/java/java-tests/testData/codeInsight/javadocIG/documentationForJdkClassWithReferencesToClassesFromJavaLang.html index 47b52ecf1cf5..ec89e92939c1 100644 --- a/java/java-tests/testData/codeInsight/javadocIG/documentationForJdkClassWithReferencesToClassesFromJavaLang.html +++ b/java/java-tests/testData/codeInsight/javadocIG/documentationForJdkClassWithReferencesToClassesFromJavaLang.html @@ -1,8 +1,8 @@ -

@Contract(pure = true) 
+
@Contract(pure = true) 
 public abstract boolean contains(
    Object o
)

   Returns true if this list contains the specified element.
   More formally, returns true if and only if this list contains
   at least one element e such that
   (o==null ? e==null : o.equals(e)).
  
-  
Overrides:
contains in interface Collection
Params:
o – element whose presence in this list is to be tested  
Returns:
true if this list contains the specified element  
Throws:
ClassCastException – if the type of the specified element          is incompatible with this list  (optional)  
NullPointerException – if the specified element is null and this          list does not permit null elements  (optional)
External
 annotations:
@org.jetbrains.annotations.Contract(pure = true)
 java.util.List<E>
 < java 1.7 >

\ No newline at end of file
+

Overrides:

contains in interface Collection

Params:

o – element whose presence in this list is to be tested

Returns:

true if this list contains the specified element

Throws:

ClassCastException – if the type of the specified element is incompatible with this list (optional)

NullPointerException – if the specified element is null and this list does not permit null elements (optional)

 java.util.List<E>
 < java 1.7 >
\ No newline at end of file diff --git a/java/java-tests/testData/codeInsight/javadocIG/documentationForUncheckedExceptionsInSupers.html b/java/java-tests/testData/codeInsight/javadocIG/documentationForUncheckedExceptionsInSupers.html index e7e074560763..c24bef6d4258 100644 --- a/java/java-tests/testData/codeInsight/javadocIG/documentationForUncheckedExceptionsInSupers.html +++ b/java/java-tests/testData/codeInsight/javadocIG/documentationForUncheckedExceptionsInSupers.html @@ -1,4 +1,4 @@ -
@Contract(pure = true) 
+
@Contract(pure = true) 
 boolean contains(
    Object o
)
 throws IOException
From interface:
java.util.Collection

   Returns true if this collection contains the specified element.
@@ -6,4 +6,4 @@
   contains at least one element e such that
   (o==null ? e==null : o.equals(e)).
  
-  
Overrides:
contains in interface Collection
contains in interface I
Params:
o – element whose presence in this collection is to be tested  
Returns:
true if this collection contains the specified          element  
Throws:
NullPointerException – before if the specified element is null and this          collection does not permit null elements          (optional) after
IOException
Inferred
 annotations:
@org.jetbrains.annotations.Contract(pure = true)
 My

\ No newline at end of file
+  
Overrides:
contains in interface Collection
contains in interface I
Params:o – element whose presence in this collection is to be tested  
Returns:
true if this collection contains the specified          element  
Throws:
NullPointerException – before if the specified element is null and this          collection does not permit null elements          (optional) after
IOException
 My

\ No newline at end of file
diff --git a/java/java-tests/testData/codeInsight/javadocIG/enumValueOf.html b/java/java-tests/testData/codeInsight/javadocIG/enumValueOf.html
index 319f73e8e2d1..f7d3a7318163 100644
--- a/java/java-tests/testData/codeInsight/javadocIG/enumValueOf.html
+++ b/java/java-tests/testData/codeInsight/javadocIG/enumValueOf.html
@@ -1,4 +1,4 @@
-
@Contract(value = "_ -> param1", pure = true) 
+
@Contract(value = "_ -> param1", pure = true) 
 static int valueOf(
    int i
)

   myjavadoc
-  
Params:
i
Returns:
Inferred
 annotations:
@org.jetbrains.annotations.Contract(value = "_ -> param1", pure = true)
 En

\ No newline at end of file
+  
Params:
i
Returns:
 En

\ No newline at end of file
diff --git a/java/java-tests/testData/codeInsight/javadocIG/inheritedParameter.html b/java/java-tests/testData/codeInsight/javadocIG/inheritedParameter.html
index 52c30bb32a6b..bc8412328af0 100644
--- a/java/java-tests/testData/codeInsight/javadocIG/inheritedParameter.html
+++ b/java/java-tests/testData/codeInsight/javadocIG/inheritedParameter.html
@@ -1 +1 @@
-
String s
s – String parameter.

\ No newline at end of file
+
String s
s – String parameter.

\ No newline at end of file
diff --git a/java/java-tests/testData/codeInsight/javadocIG/lambdaParameter.html b/java/java-tests/testData/codeInsight/javadocIG/lambdaParameter.html
index 28a798b75f01..e6304f2b0ef7 100644
--- a/java/java-tests/testData/codeInsight/javadocIG/lambdaParameter.html
+++ b/java/java-tests/testData/codeInsight/javadocIG/lambdaParameter.html
@@ -1 +1 @@
-
int a

\ No newline at end of file
+
int a

\ No newline at end of file
diff --git a/java/java-tests/testData/codeInsight/javadocIG/syntheticEnumValues.html b/java/java-tests/testData/codeInsight/javadocIG/syntheticEnumValues.html
index 035a15ea6924..cccc21a73e43 100644
--- a/java/java-tests/testData/codeInsight/javadocIG/syntheticEnumValues.html
+++ b/java/java-tests/testData/codeInsight/javadocIG/syntheticEnumValues.html
@@ -1,4 +1,4 @@
-
@Contract(value = " -> new", pure = true) 
+
@Contract(value = " -> new", pure = true) 
 public static E[] values()

   Returns an array containing the constants of this enum
   type, in the order they're declared.  This method may be
@@ -8,4 +8,4 @@
          System.out.println(c);
   

  
-  
Returns:
an array containing the constants of this enum  type, in the order they're declared
Inferred
 annotations:
@org.jetbrains.annotations.Contract(value = " -> new", pure = true)
 E

\ No newline at end of file
+

Returns:

an array containing the constants of this enum type, in the order they're declared

 E
\ No newline at end of file diff --git a/java/java-tests/testSrc/com/intellij/java/codeInspection/bytecodeAnalysis/BytecodeAnalysisIntegrationTest.java b/java/java-tests/testSrc/com/intellij/java/codeInspection/bytecodeAnalysis/BytecodeAnalysisIntegrationTest.java index 0795e252b5d8..e740ebef252b 100644 --- a/java/java-tests/testSrc/com/intellij/java/codeInspection/bytecodeAnalysis/BytecodeAnalysisIntegrationTest.java +++ b/java/java-tests/testSrc/com/intellij/java/codeInspection/bytecodeAnalysis/BytecodeAnalysisIntegrationTest.java @@ -1,4 +1,4 @@ -// Copyright 2000-2018 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. +// 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.codeInspection.bytecodeAnalysis; import com.intellij.codeInsight.AnnotationUtil; @@ -106,7 +106,7 @@ public class BytecodeAnalysisIntegrationTest extends LightJavaCodeInsightFixture checkHasGutter("org.apache.velocity.util.ExceptionUtils", "Inferred annotations available. Full signature:

\n" + - "@Contract(\"null,_,_->null\") \n" + + "@Contract(\"null,_,_->null\") \n" + "Throwable createWithCause(Class,\n" + "String,\n" + "Throwable)"); @@ -115,7 +115,7 @@ public class BytecodeAnalysisIntegrationTest extends LightJavaCodeInsightFixture public void testExternalAnnoGutter() { checkHasGutter("java.lang.String", "External annotations available. Full signature:

\n" + - "String(@NotNull char[],\n" + + "String(@NotNull char[],\n" + "int,\n" + "int)"); } diff --git a/java/openapi/resources/messages/JavaBundle.properties b/java/openapi/resources/messages/JavaBundle.properties index 50440c48ed6c..349c9f13ddc9 100644 --- a/java/openapi/resources/messages/JavaBundle.properties +++ b/java/openapi/resources/messages/JavaBundle.properties @@ -1598,11 +1598,8 @@ generate.members.implement.command=implement code.style.settings.angle.spacing.brackets=Angle brackets code.style.settings.spacing.after.closing.angle.bracket=After closing angle bracket code.style.settings.spacing.around.type.bounds=Around type bounds -non.code.annotations.explanation.external.and.inferred=External
and inferred
annotations non.code.annotations.explanation.external.and.inferred.available=External and inferred annotations available. -non.code.annotations.explanation.external=External
annotations non.code.annotations.explanation.external.available=External annotations available. -non.code.annotations.explanation.inferred=Inferred
annotations non.code.annotations.explanation.inferred.available=Inferred annotations available. non.code.annotations.explanation.full.signature=Full signature: type.migration.command.name=TypeMigration diff --git a/plugins/groovy/test/org/jetbrains/plugins/groovy/GroovyDocumentationTest.groovy b/plugins/groovy/test/org/jetbrains/plugins/groovy/GroovyDocumentationTest.groovy index deadd475c6e9..bda9b0f0341b 100644 --- a/plugins/groovy/test/org/jetbrains/plugins/groovy/GroovyDocumentationTest.groovy +++ b/plugins/groovy/test/org/jetbrains/plugins/groovy/GroovyDocumentationTest.groovy @@ -1,4 +1,4 @@ -// Copyright 2000-2021 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file. +// Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. package org.jetbrains.plugins.groovy import com.intellij.codeInsight.navigation.CtrlMouseHandler @@ -102,7 +102,7 @@ aa List ss = [] ss.collect { it } ''', '''\ -

Object it

[Inferred type] String''' +

Object it

[Inferred type] String''' } void 'test code tag'() {