From 71a05d01e7a22caa54fb3adf06b12cd48a4c20eb Mon Sep 17 00:00:00 2001 From: Roman Shevchenko Date: Mon, 12 Sep 2016 17:12:22 +0300 Subject: [PATCH] [java] allows non-members to host a javadoc comment --- .../documentation/JavaDocCommentFixer.java | 10 +++--- .../javaDoc/JavaDocLocalInspection.java | 2 +- .../lang/java/JavaDocumentationProvider.java | 11 +++---- .../com/intellij/psi/PsiDocCommentOwner.java | 21 +++--------- .../psi/PsiJavaDocumentedElement.java | 32 +++++++++++++++++++ .../intellij/psi/javadoc/PsiDocComment.java | 9 +++--- .../com/intellij/psi/impl/PsiImplUtil.java | 14 +++++++- .../psi/impl/compiled/ClsDocCommentImpl.java | 7 ++-- .../source/javadoc/PsiDocCommentImpl.java | 15 +++------ .../impl/source/javadoc/PsiDocParamRef.java | 4 +-- .../UnnecessaryInheritDocInspection.java | 2 +- 11 files changed, 75 insertions(+), 52 deletions(-) create mode 100644 java/java-psi-api/src/com/intellij/psi/PsiJavaDocumentedElement.java diff --git a/java/java-impl/src/com/intellij/codeInsight/documentation/JavaDocCommentFixer.java b/java/java-impl/src/com/intellij/codeInsight/documentation/JavaDocCommentFixer.java index 2c25a4d4f9de..1548cf64c00b 100644 --- a/java/java-impl/src/com/intellij/codeInsight/documentation/JavaDocCommentFixer.java +++ b/java/java-impl/src/com/intellij/codeInsight/documentation/JavaDocCommentFixer.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2013 JetBrains s.r.o. + * Copyright 2000-2016 JetBrains s.r.o. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -78,7 +78,7 @@ public class JavaDocCommentFixer implements DocCommentFixer { } PsiDocComment docComment = (PsiDocComment)comment; - PsiDocCommentOwner owner = docComment.getOwner(); + PsiJavaDocumentedElement owner = docComment.getOwner(); if (owner == null) { return; } @@ -155,13 +155,13 @@ public class JavaDocCommentFixer implements DocCommentFixer { } /** - * This fixer is based on existing javadoc inspections - there are two of them. One detects invalid references (to unexisted + * This fixer is based on existing javadoc inspections - there are two of them. One detects invalid references (to nonexistent * method parameter or non-declared checked exception). Another one handles all other cases (parameter documentation is missing; * parameter doesn't have a description etc). This method handles result of the second exception * * @param problems detected problems * @param comment target comment to fix - * @param document target document which contains text of the commen being fixed + * @param document target document which contains text of the comment being fixed * @param project current project */ @SuppressWarnings("unchecked") @@ -253,7 +253,7 @@ public class JavaDocCommentFixer implements DocCommentFixer { //region Calculate desired parameters order List ordered = new ArrayList<>(); - PsiDocCommentOwner owner = comment.getOwner(); + PsiJavaDocumentedElement owner = comment.getOwner(); if ((owner instanceof PsiMethod)) { PsiParameter[] parameters = ((PsiMethod)owner).getParameterList().getParameters(); for (PsiParameter parameter : parameters) { diff --git a/java/java-impl/src/com/intellij/codeInspection/javaDoc/JavaDocLocalInspection.java b/java/java-impl/src/com/intellij/codeInspection/javaDoc/JavaDocLocalInspection.java index 19483d3ba301..ad65bed44e79 100644 --- a/java/java-impl/src/com/intellij/codeInspection/javaDoc/JavaDocLocalInspection.java +++ b/java/java-impl/src/com/intellij/codeInspection/javaDoc/JavaDocLocalInspection.java @@ -335,7 +335,7 @@ public class JavaDocLocalInspection extends JavaDocLocalInspectionBase { PsiElement parent = element == null ? null : element.getParent(); if (!(parent instanceof PsiDocComment)) return null; final PsiDocComment docComment = (PsiDocComment)parent; - final PsiDocCommentOwner owner = docComment.getOwner(); + final PsiJavaDocumentedElement owner = docComment.getOwner(); if (!(owner instanceof PsiMethod)) return null; PsiParameter[] parameters = ((PsiMethod)owner).getParameterList().getParameters(); PsiParameter myParam = ContainerUtil.find(parameters, psiParameter -> myName.equals(psiParameter.getName())); diff --git a/java/java-impl/src/com/intellij/lang/java/JavaDocumentationProvider.java b/java/java-impl/src/com/intellij/lang/java/JavaDocumentationProvider.java index 6d989e4ac5b3..e8687987042c 100644 --- a/java/java-impl/src/com/intellij/lang/java/JavaDocumentationProvider.java +++ b/java/java-impl/src/com/intellij/lang/java/JavaDocumentationProvider.java @@ -374,7 +374,7 @@ public class JavaDocumentationProvider extends DocumentationProviderEx implement @Override public PsiComment findExistingDocComment(final PsiComment comment) { if (comment instanceof PsiDocComment) { - final PsiDocCommentOwner owner = ((PsiDocComment)comment).getOwner(); + final PsiJavaDocumentedElement owner = ((PsiDocComment)comment).getOwner(); if (owner != null) { return owner.getDocComment(); } @@ -395,12 +395,11 @@ public class JavaDocumentationProvider extends DocumentationProviderEx implement @Override public String generateDocumentationContentStub(PsiComment _comment) { - PsiDocCommentOwner commentOwner = ((PsiDocComment)_comment).getOwner(); - assert commentOwner != null; - final Project project = commentOwner.getProject(); + final PsiJavaDocumentedElement commentOwner = ((PsiDocComment)_comment).getOwner(); + final Project project = _comment.getProject(); final StringBuilder builder = new StringBuilder(); - final CodeDocumentationAwareCommenter commenter = (CodeDocumentationAwareCommenter)LanguageCommenters.INSTANCE - .forLanguage(commentOwner.getLanguage()); + final CodeDocumentationAwareCommenter commenter = + (CodeDocumentationAwareCommenter)LanguageCommenters.INSTANCE.forLanguage(_comment.getLanguage()); if (commentOwner instanceof PsiMethod) { PsiMethod psiMethod = (PsiMethod)commentOwner; generateParametersTakingDocFromSuperMethods(project, builder, commenter, psiMethod); diff --git a/java/java-psi-api/src/com/intellij/psi/PsiDocCommentOwner.java b/java/java-psi-api/src/com/intellij/psi/PsiDocCommentOwner.java index 90282e94159a..76b91f3fcb0e 100644 --- a/java/java-psi-api/src/com/intellij/psi/PsiDocCommentOwner.java +++ b/java/java-psi-api/src/com/intellij/psi/PsiDocCommentOwner.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2009 JetBrains s.r.o. + * Copyright 2000-2016 JetBrains s.r.o. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -15,25 +15,12 @@ */ package com.intellij.psi; -import com.intellij.psi.javadoc.PsiDocComment; -import org.jetbrains.annotations.Nullable; - /** * Represents a PSI element which can have an attached JavaDoc comment. */ -public interface PsiDocCommentOwner extends PsiMember { +public interface PsiDocCommentOwner extends PsiMember, PsiJavaDocumentedElement { /** - * Returns the JavaDoc comment for the element. - * - * @return the JavaDoc comment instance, or null if the element has no JavaDoc comment. - */ - @Nullable - PsiDocComment getDocComment(); - - /** - * Checks if the element is marked as deprecated via an annotation or JavaDoc tag. - * - * @return true is the element is marked as deprecated, false otherwise. + * Returns {@code true} if the element is marked as deprecated via an annotation or a JavaDoc tag. */ boolean isDeprecated(); -} +} \ No newline at end of file diff --git a/java/java-psi-api/src/com/intellij/psi/PsiJavaDocumentedElement.java b/java/java-psi-api/src/com/intellij/psi/PsiJavaDocumentedElement.java new file mode 100644 index 000000000000..dd7a626b5144 --- /dev/null +++ b/java/java-psi-api/src/com/intellij/psi/PsiJavaDocumentedElement.java @@ -0,0 +1,32 @@ +/* + * Copyright 2000-2016 JetBrains s.r.o. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package com.intellij.psi; + +import com.intellij.psi.javadoc.PsiDocComment; +import org.jetbrains.annotations.Nullable; + +/** + * A valid target element for a Javadoc comment (class member, module declaration etc.) + * + * @since 2016.3 + */ +public interface PsiJavaDocumentedElement extends PsiElement { + /** + * Returns the JavaDoc comment for the element, or {@code null} when the element has no JavaDoc comment. + */ + @Nullable + PsiDocComment getDocComment(); +} \ No newline at end of file diff --git a/java/java-psi-api/src/com/intellij/psi/javadoc/PsiDocComment.java b/java/java-psi-api/src/com/intellij/psi/javadoc/PsiDocComment.java index 493fdcedc386..38781d845a67 100644 --- a/java/java-psi-api/src/com/intellij/psi/javadoc/PsiDocComment.java +++ b/java/java-psi-api/src/com/intellij/psi/javadoc/PsiDocComment.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2015 JetBrains s.r.o. + * Copyright 2000-2016 JetBrains s.r.o. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -15,10 +15,9 @@ */ package com.intellij.psi.javadoc; -import com.intellij.psi.PsiComment; import com.intellij.psi.PsiDocCommentBase; -import com.intellij.psi.PsiDocCommentOwner; import com.intellij.psi.PsiElement; +import com.intellij.psi.PsiJavaDocumentedElement; import org.jetbrains.annotations.NonNls; import org.jetbrains.annotations.NotNull; import org.jetbrains.annotations.Nullable; @@ -26,13 +25,13 @@ import org.jetbrains.annotations.Nullable; /** * Represents a JavaDoc comment. */ -public interface PsiDocComment extends PsiComment, PsiDocCommentBase { +public interface PsiDocComment extends PsiDocCommentBase { /** * Returns the class, method or field described by the comment. */ @Override @Nullable - PsiDocCommentOwner getOwner(); + PsiJavaDocumentedElement getOwner(); /** * Returns the PSI elements containing the description of the element being documented diff --git a/java/java-psi-impl/src/com/intellij/psi/impl/PsiImplUtil.java b/java/java-psi-impl/src/com/intellij/psi/impl/PsiImplUtil.java index cb1a6a080c59..76f94de76469 100644 --- a/java/java-psi-impl/src/com/intellij/psi/impl/PsiImplUtil.java +++ b/java/java-psi-impl/src/com/intellij/psi/impl/PsiImplUtil.java @@ -462,11 +462,23 @@ public class PsiImplUtil { return AnnotationUtil.findAnnotation(owner, CommonClassNames.JAVA_LANG_DEPRECATED) != null; } - public static boolean isDeprecatedByDocTag(@NotNull PsiDocCommentOwner owner) { + public static boolean isDeprecatedByDocTag(@NotNull PsiJavaDocumentedElement owner) { PsiDocComment docComment = owner.getDocComment(); return docComment != null && docComment.findTagByName("deprecated") != null; } + @Nullable + public static PsiJavaDocumentedElement findDocCommentOwner(@NotNull PsiDocComment comment) { + PsiElement parent = comment.getParent(); + if (parent instanceof PsiJavaDocumentedElement) { + PsiJavaDocumentedElement owner = (PsiJavaDocumentedElement)parent; + if (owner.getDocComment() == comment) { + return owner; + } + } + return null; + } + @Nullable public static PsiAnnotationMemberValue setDeclaredAttributeValue(@NotNull PsiAnnotation psiAnnotation, @Nullable String attributeName, diff --git a/java/java-psi-impl/src/com/intellij/psi/impl/compiled/ClsDocCommentImpl.java b/java/java-psi-impl/src/com/intellij/psi/impl/compiled/ClsDocCommentImpl.java index 4b44f4a49ae6..4933aabec272 100644 --- a/java/java-psi-impl/src/com/intellij/psi/impl/compiled/ClsDocCommentImpl.java +++ b/java/java-psi-impl/src/com/intellij/psi/impl/compiled/ClsDocCommentImpl.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2012 JetBrains s.r.o. + * Copyright 2000-2016 JetBrains s.r.o. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -16,6 +16,7 @@ package com.intellij.psi.impl.compiled; import com.intellij.psi.*; +import com.intellij.psi.impl.PsiImplUtil; import com.intellij.psi.impl.source.tree.JavaDocElementType; import com.intellij.psi.impl.source.tree.TreeElement; import com.intellij.psi.javadoc.PsiDocComment; @@ -62,8 +63,8 @@ class ClsDocCommentImpl extends ClsElementImpl implements PsiDocComment, JavaTok } @Override - public PsiDocCommentOwner getOwner() { - return myParent; + public PsiJavaDocumentedElement getOwner() { + return PsiImplUtil.findDocCommentOwner(this); } @Override diff --git a/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocCommentImpl.java b/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocCommentImpl.java index 959df6e4a511..80d7ffcd80da 100644 --- a/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocCommentImpl.java +++ b/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocCommentImpl.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2012 JetBrains s.r.o. + * Copyright 2000-2016 JetBrains s.r.o. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -20,6 +20,7 @@ import com.intellij.openapi.diagnostic.Logger; import com.intellij.openapi.project.Project; import com.intellij.psi.*; import com.intellij.psi.codeStyle.JavaCodeStyleSettingsFacade; +import com.intellij.psi.impl.PsiImplUtil; import com.intellij.psi.impl.source.Constants; import com.intellij.psi.impl.source.SourceTreeToPsiMap; import com.intellij.psi.impl.source.tree.*; @@ -58,16 +59,8 @@ public class PsiDocCommentImpl extends LazyParseablePsiElement implements PsiDoc } @Override - public PsiDocCommentOwner getOwner() { - final PsiElement parent = getParent(); - if (parent instanceof PsiDocCommentOwner) { - final PsiDocCommentOwner owner = (PsiDocCommentOwner)parent; - if (owner.getDocComment() == this) { - return owner; - } - } - - return null; + public PsiJavaDocumentedElement getOwner() { + return PsiImplUtil.findDocCommentOwner(this); } @Override diff --git a/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocParamRef.java b/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocParamRef.java index 21e8c6cbbc38..2bbedf28a298 100644 --- a/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocParamRef.java +++ b/java/java-psi-impl/src/com/intellij/psi/impl/source/javadoc/PsiDocParamRef.java @@ -1,5 +1,5 @@ /* - * Copyright 2000-2012 JetBrains s.r.o. + * Copyright 2000-2016 JetBrains s.r.o. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. @@ -47,7 +47,7 @@ public class PsiDocParamRef extends CompositePsiElement implements PsiDocTagValu public PsiReference getReference() { final PsiDocComment comment = PsiTreeUtil.getParentOfType(this, PsiDocComment.class); if (comment == null) return null; - final PsiDocCommentOwner owner = comment.getOwner(); + final PsiJavaDocumentedElement owner = comment.getOwner(); if (!(owner instanceof PsiMethod) && !(owner instanceof PsiClass)) return null; final ASTNode valueToken = findChildByType(JavaDocTokenType.DOC_TAG_VALUE_TOKEN); diff --git a/plugins/InspectionGadgets/InspectionGadgetsAnalysis/src/com/siyeh/ig/javadoc/UnnecessaryInheritDocInspection.java b/plugins/InspectionGadgets/InspectionGadgetsAnalysis/src/com/siyeh/ig/javadoc/UnnecessaryInheritDocInspection.java index 901e70f256af..cbda63d70bf7 100644 --- a/plugins/InspectionGadgets/InspectionGadgetsAnalysis/src/com/siyeh/ig/javadoc/UnnecessaryInheritDocInspection.java +++ b/plugins/InspectionGadgets/InspectionGadgetsAnalysis/src/com/siyeh/ig/javadoc/UnnecessaryInheritDocInspection.java @@ -133,7 +133,7 @@ public class UnnecessaryInheritDocInspection extends BaseInspection { if (docComment == null) { return; } - final PsiDocCommentOwner owner = docComment.getOwner(); + final PsiJavaDocumentedElement owner = docComment.getOwner(); if (owner instanceof PsiField) { registerError(tag, WarningType.FIELD); return;