Fix Missing documentation inspection for primary ctor properties

#KT-20954 fixed
#KT-21005 fixed

idea/ide-common/src/org/jetbrains/kotlin/idea/kdoc/findKDoc.kt

@@ -17,56 +17,79 @@
 package org.jetbrains.kotlin.idea.kdoc
 
 import com.intellij.psi.PsiElement
-import org.jetbrains.kotlin.descriptors.*
+import org.jetbrains.kotlin.descriptors.CallableDescriptor
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptorWithSource
+import org.jetbrains.kotlin.idea.caches.resolve.resolveToDescriptorIfAny
 import org.jetbrains.kotlin.kdoc.parser.KDocKnownTag
 import org.jetbrains.kotlin.kdoc.psi.api.KDoc
 import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
-import org.jetbrains.kotlin.psi.KtDeclaration
-import org.jetbrains.kotlin.psi.KtPrimaryConstructor
-import org.jetbrains.kotlin.psi.psiUtil.getParentOfType
+import org.jetbrains.kotlin.psi.*
+import org.jetbrains.kotlin.psi.psiUtil.*
 import org.jetbrains.kotlin.resolve.DescriptorToSourceUtils
 
 fun DeclarationDescriptor.findKDoc(
-        descriptorToPsi: (DeclarationDescriptorWithSource) -> PsiElement? = { DescriptorToSourceUtils.descriptorToDeclaration(it) }
+    descriptorToPsi: (DeclarationDescriptorWithSource) -> PsiElement? = { DescriptorToSourceUtils.descriptorToDeclaration(it) }
 ): KDocTag? {
     if (this is DeclarationDescriptorWithSource) {
-        var psiDeclaration = descriptorToPsi(this)?.navigationElement
-        // KDoc for primary constructor is located inside of its class KDoc
-        if (psiDeclaration is KtPrimaryConstructor) {
-            psiDeclaration = psiDeclaration.getContainingClassOrObject()
-        }
+        val psiDeclaration = descriptorToPsi(this)?.navigationElement
+        return (psiDeclaration as? KtElement)?.findKDoc(descriptorToPsi)
+    }
+    return null
+}
 
-        if (psiDeclaration is KtDeclaration) {
-            val kdoc = psiDeclaration.docComment
-            if (kdoc != null) {
-                if (this is ConstructorDescriptor) {
-                    // ConstructorDescriptor resolves to the same JetDeclaration
-                    val constructorSection = kdoc.findSectionByTag(KDocKnownTag.CONSTRUCTOR)
-                    if (constructorSection != null) {
-                        return constructorSection
-                    }
+
+fun KtElement.findKDoc(descriptorToPsi: (DeclarationDescriptorWithSource) -> PsiElement?): KDocTag? {
+    var psiDeclaration = this
+
+    // KDoc for primary constructor is located inside of its class KDoc
+    if (psiDeclaration is KtPrimaryConstructor) {
+        psiDeclaration = psiDeclaration.getContainingClassOrObject()
+    }
+
+    if (psiDeclaration is KtDeclaration) {
+        val kdoc = psiDeclaration.docComment
+        if (kdoc != null) {
+            if (this is KtConstructor<*>) {
+                // ConstructorDescriptor resolves to the same JetDeclaration
+                val constructorSection = kdoc.findSectionByTag(KDocKnownTag.CONSTRUCTOR)
+                if (constructorSection != null) {
+                    return constructorSection
                 }
-                return kdoc.getDefaultSection()
+            }
+            return kdoc.getDefaultSection()
+        }
+    }
+
+
+    if (this is KtParameter) {
+        val classKDoc = containingClassOrObject?.getChildOfType<KDoc>()
+        val subjectName = name
+        if (classKDoc != null && subjectName != null) {
+            val propertySection =
+                classKDoc.findSectionByTag(KDocKnownTag.PROPERTY, subjectName)?.takeIf { this.isPropertyParameter() }
+                        ?: classKDoc.findDescendantOfType<KDocTag> { it.knownTag == KDocKnownTag.PARAM && it.getSubjectName() == subjectName }
+            if (propertySection != null) {
+                return propertySection
             }
         }
     }
 
-    if (this is PropertyDescriptor) {
-        val containingClassDescriptor = this.containingDeclaration as? ClassDescriptor
-        if (containingClassDescriptor != null) {
-            val classKDoc = containingClassDescriptor.findKDoc(descriptorToPsi)?.getParentOfType<KDoc>(false)
-            if (classKDoc != null) {
-                val propertySection = classKDoc.findSectionByTag(KDocKnownTag.PROPERTY,
-                                                                 getName().asString())
-                if (propertySection != null) {
-                    return propertySection
-                }
+    if (this is KtProperty) {
+        val classKDoc = containingClass()?.getChildOfType<KDoc>()
+        val subjectName = name
+        if (classKDoc != null && subjectName != null) {
+            val propertySection = classKDoc.findSectionByTag(KDocKnownTag.PROPERTY, subjectName)
+            if (propertySection != null) {
+                return propertySection
             }
         }
     }
 
-    if (this is CallableDescriptor) {
-        for (baseDescriptor in this.overriddenDescriptors) {
+    if (this is KtCallableDeclaration) {
+        val descriptor = this.resolveToDescriptorIfAny() as? CallableDescriptor ?: return null
+
+        for (baseDescriptor in descriptor.overriddenDescriptors) {
             val baseKDoc = baseDescriptor.original.findKDoc(descriptorToPsi)
             if (baseKDoc != null) {
                 return baseKDoc
@@ -75,5 +98,4 @@ fun DeclarationDescriptor.findKDoc(
     }
 
     return null
-}
-
+}

idea/src/org/jetbrains/kotlin/idea/inspections/describeDeclaration.kt

@@ -17,17 +17,19 @@
 package org.jetbrains.kotlin.idea.inspections
 
 import org.jetbrains.kotlin.psi.*
+import org.jetbrains.kotlin.psi.psiUtil.isPropertyParameter
 
 /**
- * @returns string description of declaration, like Function ''name''
+ * @return string description of declaration, like `Function "describe"`
  */
 fun KtNamedDeclaration.describe(): String? = when (this) {
-    is KtClass -> "Class ''$name''"
-    is KtObjectDeclaration -> "Object ''$name''"
-    is KtNamedFunction -> "Function ''$name''"
+    is KtClass -> "Class \"$name\""
+    is KtObjectDeclaration -> "Object \"$name\""
+    is KtNamedFunction -> "Function \"$name\""
     is KtSecondaryConstructor -> "Constructor"
-    is KtProperty, is KtParameter -> "Property ''$name''"
-    is KtTypeParameter -> "Type parameter ''$name''"
-    is KtTypeAlias -> "Type alias ''$name''"
+    is KtProperty -> "Property \"$name\""
+    is KtParameter -> if (this.isPropertyParameter()) "Property \"$name\"" else "Parameter \"$name\""
+    is KtTypeParameter -> "Type parameter \"$name\""
+    is KtTypeAlias -> "Type alias \"$name\""
     else -> null
 }

idea/src/org/jetbrains/kotlin/idea/inspections/kdoc/KDocMissingDocumentationInspection.kt

@@ -14,7 +14,6 @@ import com.intellij.openapi.project.Project
 import com.intellij.psi.PsiElementVisitor
 import com.siyeh.ig.psiutils.TestUtils
 import org.jetbrains.kotlin.descriptors.DeclarationDescriptorWithVisibility
-import org.jetbrains.kotlin.descriptors.MemberDescriptor
 import org.jetbrains.kotlin.idea.caches.resolve.resolveToDescriptorIfAny
 import org.jetbrains.kotlin.idea.codeInsight.DescriptorToSourceUtilsIde
 import org.jetbrains.kotlin.idea.core.unblockDocument
@@ -30,27 +29,29 @@ import org.jetbrains.kotlin.psi.psiUtil.endOffset
 import org.jetbrains.kotlin.psi.psiUtil.getChildOfType
 import org.jetbrains.kotlin.psi.psiUtil.getParentOfType
 import org.jetbrains.kotlin.resolve.descriptorUtil.isEffectivelyPublicApi
-import org.jetbrains.kotlin.resolve.lazy.BodyResolveMode
 
 class KDocMissingDocumentationInspection : AbstractKotlinInspection() {
     override fun buildVisitor(holder: ProblemsHolder, isOnTheFly: Boolean): PsiElementVisitor =
-            namedDeclarationVisitor { element ->
-                if (TestUtils.isInTestSourceContent(element)) {
-                    return@namedDeclarationVisitor
-                }
-                val nameIdentifier = element.nameIdentifier
-                val descriptor = element.resolveToDescriptorIfAny(BodyResolveMode.FULL)
-                        as? DeclarationDescriptorWithVisibility
-                        as? MemberDescriptor ?: return@namedDeclarationVisitor
-                if (nameIdentifier != null && descriptor.isEffectivelyPublicApi) {
-                    if (descriptor.findKDoc { DescriptorToSourceUtilsIde.getAnyDeclaration(element.project, it) } == null) {
+        namedDeclarationVisitor { element ->
+            if (TestUtils.isInTestSourceContent(element)) {
+                return@namedDeclarationVisitor
+            }
+            val nameIdentifier = element.nameIdentifier
+            if (nameIdentifier != null) {
+                if (element.findKDoc { DescriptorToSourceUtilsIde.getAnyDeclaration(element.project, it) } == null) {
+                    val descriptor =
+                        element.resolveToDescriptorIfAny() as? DeclarationDescriptorWithVisibility ?: return@namedDeclarationVisitor
+                    if (descriptor.isEffectivelyPublicApi) {
                         val message = element.describe()?.let { "$it is missing documentation" } ?: "Missing documentation"
                         holder.registerProblem(nameIdentifier, message, AddDocumentationFix())
                     }
                 }
-
             }
 
+        }
+
+    override fun runForWholeFile(): Boolean = true
+
     class AddDocumentationFix : LocalQuickFix {
         override fun getName(): String = "Add documentation"
 

idea/testData/inspectionsLocal/kdocMissingDocumentation/primaryConstructorProperty.kt

@@ -0,0 +1,6 @@
+// PROBLEM: none
+
+/**
+ * @property a it is A
+ */
+class A(val <caret>a: A)

idea/testData/inspectionsLocal/kdocMissingDocumentation/primaryConstructorPropertyAsParam.kt

@@ -0,0 +1,6 @@
+// PROBLEM: none
+
+/**
+ * @param a is is A
+ */
+class A(val <caret>a: A)

idea/testData/inspectionsLocal/kdocMissingDocumentation/simple.kt

@@ -1,3 +1,3 @@
-// PROBLEM: "Class ''A'' is missing documentation"
+// PROBLEM: "Class "A" is missing documentation"
 
 class <caret>A

idea/testData/inspectionsLocal/kdocMissingDocumentation/simple.kt.after

@@ -1,4 +1,4 @@
-// PROBLEM: "Class ''A'' is missing documentation"
+// PROBLEM: "Class "A" is missing documentation"
 
 /**
  * <caret>

idea/testData/kdoc/highlighting/MissingDocumentation.kt

@@ -1,6 +1,6 @@
 
-public fun <warning descr="Function ''publicUndocumentedFun'' is missing documentation">publicUndocumentedFun</warning>() {}
-fun <warning descr="Function ''defaultUndocumentedFun'' is missing documentation">defaultUndocumentedFun</warning>() {}
+public fun <warning descr="Function \"publicUndocumentedFun\" is missing documentation">publicUndocumentedFun</warning>() {}
+fun <warning descr="Function \"defaultUndocumentedFun\" is missing documentation">defaultUndocumentedFun</warning>() {}
 
 /** Some documentation */
 public fun publicDocumentedFun() {}
@@ -13,8 +13,8 @@ internal fun internalUndocumentedFun() {}
 
 
 
-public class <warning descr="Class ''publicUndocumentedClass'' is missing documentation">publicUndocumentedClass</warning>() {}
-class <warning descr="Class ''defaultUndocumentedClass'' is missing documentation">defaultUndocumentedClass</warning>() {}
+public class <warning descr="Class \"publicUndocumentedClass\" is missing documentation">publicUndocumentedClass</warning>() {}
+class <warning descr="Class \"defaultUndocumentedClass\" is missing documentation">defaultUndocumentedClass</warning>() {}
 
 /** Some documentation */
 public class publicDocumentedClass() {}
@@ -66,12 +66,12 @@ private class GrandChildClass : ChildClass() {
     override public val internalUndocumentedProperty: Int = 6
 }
 
-open class <warning descr="Class ''SomeClass'' is missing documentation">SomeClass</warning> {
-    protected fun <warning descr="Function ''testProtected'' is missing documentation">testProtected</warning>() = 1
+open class <warning descr="Class \"SomeClass\" is missing documentation">SomeClass</warning> {
+    protected fun <warning descr="Function \"testProtected\" is missing documentation">testProtected</warning>() = 1
 }
 
-class <warning descr="Class ''FinalClassWithProtected'' is missing documentation">FinalClassWithProtected</warning> {
-    protected fun <warning descr="Function ''testProtected'' is missing documentation">testProtected</warning>() = 1
+class <warning descr="Class \"FinalClassWithProtected\" is missing documentation">FinalClassWithProtected</warning> {
+    protected fun <warning descr="Function \"testProtected\" is missing documentation">testProtected</warning>() = 1
 }
 
 private class PrimaryCon(val p: String)

idea/tests/org/jetbrains/kotlin/idea/inspections/LocalInspectionTestGenerated.java

@@ -1590,6 +1590,18 @@ public class LocalInspectionTestGenerated extends AbstractLocalInspectionTest {
             KotlinTestUtils.assertAllTestsPresentByMetadata(this.getClass(), new File("idea/testData/inspectionsLocal/kdocMissingDocumentation"), Pattern.compile("^([\\w\\-_]+)\\.(kt|kts)$"), TargetBackend.ANY, true);
         }
 
+        @TestMetadata("primaryConstructorProperty.kt")
+        public void testPrimaryConstructorProperty() throws Exception {
+            String fileName = KotlinTestUtils.navigationMetadata("idea/testData/inspectionsLocal/kdocMissingDocumentation/primaryConstructorProperty.kt");
+            doTest(fileName);
+        }
+
+        @TestMetadata("primaryConstructorPropertyAsParam.kt")
+        public void testPrimaryConstructorPropertyAsParam() throws Exception {
+            String fileName = KotlinTestUtils.navigationMetadata("idea/testData/inspectionsLocal/kdocMissingDocumentation/primaryConstructorPropertyAsParam.kt");
+            doTest(fileName);
+        }
+
         @TestMetadata("simple.kt")
         public void testSimple() throws Exception {
             String fileName = KotlinTestUtils.navigationMetadata("idea/testData/inspectionsLocal/kdocMissingDocumentation/simple.kt");