Merge pull request #550 from JetBrains/kdoc-inherit

allow inheriting doc comments from base classes

compiler/frontend/src/org/jetbrains/kotlin/kdoc/KDocFinder.kt

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2010-2015 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 org.jetbrains.kotlin.kdoc
+
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptorWithSource
+import org.jetbrains.kotlin.resolve.source.PsiSourceElement
+import org.jetbrains.kotlin.psi.JetDeclaration
+import org.jetbrains.kotlin.descriptors.FunctionDescriptor
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag
+
+fun findKDoc(declaration: DeclarationDescriptor): KDocTag? {
+    if (declaration is DeclarationDescriptorWithSource) {
+        val psiDeclaration = (declaration.getSource() as? PsiSourceElement)?.psi?.getNavigationElement()
+        if (psiDeclaration is JetDeclaration) {
+            val kdoc = psiDeclaration.getDocComment()
+            if (kdoc != null) {
+                return kdoc.getDefaultSection()
+            }
+        }
+    }
+
+    if (declaration is FunctionDescriptor) {
+        for (baseDescriptor in declaration.getOverriddenDescriptors()) {
+            val baseKDoc = findKDoc(baseDescriptor)
+            if (baseKDoc != null) {
+                return baseKDoc
+            }
+        }
+    }
+
+    return null
+}

idea/src/org/jetbrains/kotlin/idea/JetQuickDocumentationProvider.java

@@ -27,7 +27,8 @@ import org.jetbrains.annotations.NotNull;
 import org.jetbrains.kotlin.asJava.KotlinLightMethod;
 import org.jetbrains.kotlin.descriptors.DeclarationDescriptor;
 import org.jetbrains.kotlin.idea.caches.resolve.ResolvePackage;
-import org.jetbrains.kotlin.kdoc.psi.api.KDoc;
+import org.jetbrains.kotlin.kdoc.KdocPackage;
+import org.jetbrains.kotlin.kdoc.psi.impl.KDocTag;
 import org.jetbrains.kotlin.psi.JetDeclaration;
 import org.jetbrains.kotlin.psi.JetPackageDirective;
 import org.jetbrains.kotlin.psi.JetReferenceExpression;
@@ -90,11 +91,7 @@ public class JetQuickDocumentationProvider extends AbstractDocumentationProvider
             renderedDecl = "<pre>" + DescriptorRenderer.HTML_NAMES_WITH_SHORT_TYPES.render(declarationDescriptor) + "</pre>";
         }
 
-        PsiElement navigationElement = declaration.getNavigationElement();
-        if (navigationElement instanceof JetDeclaration) {
-            declaration = (JetDeclaration) navigationElement;
-        }
-        KDoc comment = declaration.getDocComment();
+        KDocTag comment = KdocPackage.findKDoc(declarationDescriptor);
         if (comment != null) {
             renderedDecl = renderedDecl + "<br/>" + kDocToHtml(comment);
         }
@@ -115,9 +112,9 @@ public class JetQuickDocumentationProvider extends AbstractDocumentationProvider
         return null;
     }
 
-    private static String kDocToHtml(@NotNull KDoc comment) {
+    private static String kDocToHtml(@NotNull KDocTag comment) {
         // TODO: Parse and show markdown comments as html
-        String content = comment.getDefaultSection().getContentWithTags();
+        String content = comment.getContentWithTags();
         String htmlContent = StringUtil.replace(content, "\n", "<br/>")
                 .replaceAll("(@param)\\s+(\\w+)", "@param - <i>$2</i>")
                 .replaceAll("(@\\w+)", "<b>$1</b>");

idea/testData/editor/quickDoc/OnInheritedMethodUsage.kt

@@ -0,0 +1,17 @@
+open class C() {
+    /**
+     * This method returns zero.
+     */
+    open fun foo(): Int = 0
+}
+
+class D(): C() {
+    override fun foo(): Int = 1
+}
+
+
+fun test() {
+    D().f<caret>oo()
+}
+
+// INFO: <b>internal</b> <b>open</b> <b>fun</b> foo(): Int<br/><p>This method returns zero.</p>

idea/tests/org/jetbrains/kotlin/idea/editor/quickDoc/JetQuickDocProviderTestGenerated.java

@@ -17,7 +17,6 @@
 package org.jetbrains.kotlin.idea.editor.quickDoc;
 
 import com.intellij.testFramework.TestDataPath;
-import org.jetbrains.kotlin.test.InnerTestClasses;
 import org.jetbrains.kotlin.test.JUnit3RunnerWithInners;
 import org.jetbrains.kotlin.test.JetTestUtils;
 import org.jetbrains.kotlin.test.TestMetadata;
@@ -96,6 +95,12 @@ public class JetQuickDocProviderTestGenerated extends AbstractJetQuickDocProvide
         doTest(fileName);
     }
 
+    @TestMetadata("OnInheritedMethodUsage.kt")
+    public void testOnInheritedMethodUsage() throws Exception {
+        String fileName = JetTestUtils.navigationMetadata("idea/testData/editor/quickDoc/OnInheritedMethodUsage.kt");
+        doTest(fileName);
+    }
+
     @TestMetadata("OnMethodUsage.kt")
     public void testOnMethodUsage() throws Exception {
         String fileName = JetTestUtils.navigationMetadata("idea/testData/editor/quickDoc/OnMethodUsage.kt");