[javadoc] ability to provide delegate to copy javadoc from

java/java-impl/src/com/intellij/codeInsight/javadoc/DocumentationDelegateProvider.java

@@ -0,0 +1,69 @@
+/*
+ * 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.codeInsight.javadoc;
+
+import com.intellij.openapi.extensions.ExtensionPointName;
+import com.intellij.psi.PsiDocCommentOwner;
+import com.intellij.psi.PsiMember;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+public abstract class DocumentationDelegateProvider {
+
+  public static final ExtensionPointName<DocumentationDelegateProvider> EP_NAME = ExtensionPointName.create(
+    "com.intellij.documentationDelegateProvider"
+  );
+
+  /**
+   * <p>
+   * Computes PsiDocCommentOwner to get documentation from.
+   * </p>
+   * <p>
+   * Suppose there is a <code>Foo#bar()</code> with doc and <code>Baz#bar()</code> without doc:
+   * <pre>
+   * class Foo {
+   *   /**
+   *   * Some javadoc
+   *   *&#47;
+   *   void bar() {}
+   * }
+   * class Baz {
+   *   void bar() {}
+   * }
+   * </pre>
+   * If it is needed to display doc from <code>Foo#bar()</code> when doc for <code>Baz#bar()</code> is queried
+   * then this method should return PsiMethod corresponding to <code>Foo#bar()</code> for PsiMethod corresponding to <code>Baz#bar()</code>.
+   * <br>
+   * The copied documentation will include <i>Description copied from</i> link.
+   * </p>
+   *
+   * @param member method to search delegate for.
+   * @return delegate PsiDocCommentOwner instance.
+   */
+  @Nullable
+  public abstract PsiDocCommentOwner computeDocumentationDelegate(@NotNull PsiMember member);
+
+  @Nullable
+  public static PsiDocCommentOwner findDocumentationDelegate(@NotNull PsiMember method) {
+    for (DocumentationDelegateProvider delegator : EP_NAME.getExtensions()) {
+      PsiDocCommentOwner type = delegator.computeDocumentationDelegate(method);
+      if (type != null) {
+        return type;
+      }
+    }
+    return null;
+  }
+}

java/java-impl/src/com/intellij/codeInsight/javadoc/JavaDocInfoGenerator.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.
@@ -2223,9 +2223,14 @@ public class JavaDocInfoGenerator {
     if (aClass == null) {
       return null;
     }
-    
+
+    Pair<T, InheritDocProvider<T>> delegate = findInheritDocTagInDelegate(aMethod, loc);
+    if (delegate != null) {
+      return delegate;
+    }
+
     if (aClass instanceof PsiAnonymousClass) {
-      return searchDocTagInSupers(new PsiClassType[] {((PsiAnonymousClass)aClass).getBaseClassType()}, aMethod, loc, visitedClasses);
+      return searchDocTagInSupers(new PsiClassType[]{((PsiAnonymousClass)aClass).getBaseClassType()}, aMethod, loc, visitedClasses);
     }
 
     PsiClassType[] implementsTypes = aClass.getImplementsListTypes();
@@ -2239,14 +2244,44 @@ public class JavaDocInfoGenerator {
     return searchDocTagInSupers(extendsTypes, aMethod, loc, visitedClasses);
   }
 
-  @Nullable private <T> Pair<T, InheritDocProvider<T>> findInheritDocTag(PsiMethod method, DocTagLocator<T> loc) {
-    PsiClass aClass = method.getContainingClass();
+  @Nullable
+  private <T> Pair<T, InheritDocProvider<T>> findInheritDocTagInDelegate(PsiMethod method, DocTagLocator<T> loc) {
+    PsiMethod delegateMethod = findDelegateMethod(method);
+    if (delegateMethod == null) return null;
 
+    PsiClass containingClass = delegateMethod.getContainingClass();
+    if (containingClass == null) return null;
+
+    T tag = loc.find(delegateMethod, getDocComment(delegateMethod));
+    if (tag == null) return null;
+
+    return Pair.create(tag, new InheritDocProvider<T>() {
+      @Override
+      public Pair<T, InheritDocProvider<T>> getInheritDoc() {
+        return findInheritDocTag(delegateMethod, loc);
+      }
+
+      @Override
+      public PsiClass getElement() {
+        return containingClass;
+      }
+    });
+  }
+
+  @Nullable
+  private static PsiMethod findDelegateMethod(@NotNull PsiMethod method) {
+    PsiDocCommentOwner delegate = DocumentationDelegateProvider.findDocumentationDelegate(method);
+    return delegate instanceof PsiMethod ? (PsiMethod)delegate : null;
+  }
+
+  @Nullable
+  private <T> Pair<T, InheritDocProvider<T>> findInheritDocTag(PsiMethod method, DocTagLocator<T> loc) {
+    PsiClass aClass = method.getContainingClass();
     if (aClass == null) return null;
 
     return findInheritDocTagInClass(method, aClass, loc, new HashSet<PsiClass>());
   }
-  
+
   private static class ParamInfo {
     private final String name;
     private final PsiDocTag docTag;

java/java-tests/testSrc/com/intellij/codeInsight/JavaDocumentationTest.groovy

@@ -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.
@@ -16,11 +16,14 @@
 package com.intellij.codeInsight
 
 import com.intellij.codeInsight.documentation.DocumentationManager
+import com.intellij.codeInsight.javadoc.DocumentationDelegateProvider
 import com.intellij.codeInsight.navigation.CtrlMouseHandler
 import com.intellij.lang.java.JavaDocumentationProvider
+import com.intellij.psi.JavaPsiFacade
 import com.intellij.psi.PsiExpressionList
 import com.intellij.psi.PsiMethod
 import com.intellij.psi.util.PsiTreeUtil
+import com.intellij.testFramework.PlatformTestUtil
 import com.intellij.testFramework.fixtures.LightCodeInsightFixtureTestCase
 
 /**
@@ -193,6 +196,41 @@ class JavaDocumentationTest extends LightCodeInsightFixtureTestCase {
     assert doc == expected
   }
 
+  public void testMethodToMethodDelegate() {
+    DocumentationDelegateProvider provider = {
+      if (it instanceof PsiMethod && it.name == 'foo') {
+        JavaPsiFacade.getInstance(project).findClass('Foo', it.resolveScope)?.findMethodBySignature(it, false)
+      }
+    }
+    PlatformTestUtil.registerExtension DocumentationDelegateProvider.EP_NAME, provider, testRootDisposable
+
+    configure '''\
+class Foo {
+  /**
+  * Some doc
+  */
+  void foo() {}
+}
+
+class Bar {
+  void fo<caret>o() {}
+}
+'''
+    def method = PsiTreeUtil.getParentOfType(myFixture.file.findElementAt(myFixture.editor.caretModel.offset), PsiMethod.class)
+    def doc = new JavaDocumentationProvider().generateDoc(method, null)
+
+    String expected = "<html><head>$STYLE_BLOCK</head><body>" +
+                      "<small><b><a href=\"psi_element://Bar\"><code>Bar</code></a></b></small>" +
+                      "<PRE>void&nbsp;<b>foo</b>()</PRE>" +
+                      "<DD><DL><DT>" +
+                      "<b>Description copied from class:</b>&nbsp;<a href=\"psi_element://Foo\"><code>Foo</code></a><br>" +
+                      "\n    Some doc\n  " +
+                      "</DD></DL></DD>" +
+                      "</body></html>"
+
+    assert doc == expected
+  }
+
   private void configure(String text) {
     myFixture.configureByText 'a.java', text
   }

resources/src/META-INF/IdeaPlugin.xml

@@ -310,6 +310,8 @@
     </extensionPoint>
 
     <extensionPoint name="library.javaSourceRootDetector" interface="com.intellij.openapi.roots.libraries.ui.RootDetector"/>
+
+    <extensionPoint name="documentationDelegateProvider" interface="com.intellij.codeInsight.javadoc.DocumentationDelegateProvider"/>
   </extensionPoints>
 
   <extensions defaultExtensionNs="com.intellij">