link to JDK classes (KT-10452)

10 files changed, 81 insertions, 7 deletions

diff --git a/core/src/main/kotlin/Kotlin/DeclarationLinkResolver.kt b/core/src/main/kotlin/Kotlin/DeclarationLinkResolver.kt
index 2569bc71..c1c301f2 100644
--- a/core/src/main/kotlin/Kotlin/DeclarationLinkResolver.kt
+++ b/core/src/main/kotlin/Kotlin/DeclarationLinkResolver.kt
@@ -1,9 +1,15 @@
 package org.jetbrains.dokka
 
 import com.google.inject.Inject
+import com.intellij.psi.PsiMethod
 import org.jetbrains.kotlin.descriptors.CallableMemberDescriptor
 import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
 import org.jetbrains.kotlin.idea.kdoc.resolveKDocLink
+import org.jetbrains.kotlin.load.java.descriptors.JavaClassDescriptor
+import org.jetbrains.kotlin.load.java.descriptors.JavaMethodDescriptor
+import org.jetbrains.kotlin.name.Name
+import org.jetbrains.kotlin.resolve.DescriptorUtils
+import org.jetbrains.kotlin.resolve.source.PsiSourceElement
 
 class DeclarationLinkResolver
         @Inject constructor(val resolutionFacade: DokkaResolutionFacade,
@@ -20,6 +26,10 @@ class DeclarationLinkResolver
         // don't include unresolved links in generated doc
         // assume that if an href doesn't contain '/', it's not an attempt to reference an external file
         if (symbol != null) {
+            val jdkHref = buildJdkLink(symbol)
+            if (jdkHref != null) {
+                return ContentExternalLink(jdkHref)
+            }
             return ContentNodeLazyLink(href, { -> refGraph.lookup(symbol.signature()) })
         }
         if ("/" in href) {
@@ -40,4 +50,26 @@ class DeclarationLinkResolver
         return symbol
     }
 
+    fun buildJdkLink(symbol: DeclarationDescriptor): String? {
+        if (symbol is JavaClassDescriptor) {
+            val fqName = DescriptorUtils.getFqName(symbol)
+            if (fqName.startsWith(Name.identifier("java")) || fqName.startsWith(Name.identifier("javax"))) {
+                return javadocRoot + fqName.asString().replace(".", "/") + ".html"
+            }
+        }
+        else if (symbol is JavaMethodDescriptor) {
+            val containingClass = symbol.containingDeclaration as? JavaClassDescriptor ?: return null
+            val containingClassLink = buildJdkLink(containingClass)
+            if (containingClassLink != null) {
+                val psi = (symbol.original.source as? PsiSourceElement)?.psi as? PsiMethod
+                if (psi != null) {
+                    val params = psi.parameterList.parameters.joinToString { it.type.canonicalText }
+                    return containingClassLink + "#" + symbol.name + "(" + params + ")"
+                }
+            }
+        }
+        return null
+    }
+
+    private val javadocRoot = "http://docs.oracle.com/javase/6/docs/api/"
 }
\ No newline at end of file
diff --git a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
index f3b206c6..4694bcdf 100644
--- a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
+++ b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
@@ -66,7 +66,8 @@ class DocumentationBuilder
                             val descriptorDocumentationParser: DescriptorDocumentationParser,
                             val options: DocumentationOptions,
                             val refGraph: NodeReferenceGraph,
-                            val logger: DokkaLogger)
+                            val logger: DokkaLogger,
+                            val linkResolver: DeclarationLinkResolver)
 {
     val visibleToDocumentation = setOf(Visibilities.PROTECTED, Visibilities.PUBLIC)
     val boringBuiltinClasses = setOf(
@@ -180,8 +181,14 @@ class DocumentationBuilder
             node.appendTextNode("?", NodeKind.NullabilityModifier)
         }
         if (classifierDescriptor != null) {
-            link(node, classifierDescriptor,
-                    if (classifierDescriptor.isBoringBuiltinClass()) RefKind.HiddenLink else RefKind.Link)
+            val jdkLink = linkResolver.buildJdkLink(classifierDescriptor)
+            if (jdkLink != null) {
+                node.append(DocumentationNode(jdkLink, Content.Empty, NodeKind.ExternalLink), RefKind.Link)
+            }
+            else {
+                link(node, classifierDescriptor,
+                        if (classifierDescriptor.isBoringBuiltinClass()) RefKind.HiddenLink else RefKind.Link)
+            }
         }
 
         append(node, RefKind.Detail)
diff --git a/core/src/main/kotlin/Model/Content.kt b/core/src/main/kotlin/Model/Content.kt
index 1bf1da48..4c69f6cb 100644
--- a/core/src/main/kotlin/Model/Content.kt
+++ b/core/src/main/kotlin/Model/Content.kt
@@ -158,7 +158,11 @@ fun ContentBlock.code(body: ContentBlock.() -> Unit) {
 }
 
 fun ContentBlock.link(to: DocumentationNode, body: ContentBlock.() -> Unit) {
-    val block = ContentNodeDirectLink(to)
+    val block = if (to.kind == NodeKind.ExternalLink)
+        ContentExternalLink(to.name)
+    else
+        ContentNodeDirectLink(to)
+
     block.body()
     append(block)
 }
diff --git a/core/src/main/kotlin/Model/DocumentationNode.kt b/core/src/main/kotlin/Model/DocumentationNode.kt
index dcb50e8f..3cedb8e6 100644
--- a/core/src/main/kotlin/Model/DocumentationNode.kt
+++ b/core/src/main/kotlin/Model/DocumentationNode.kt
@@ -43,6 +43,8 @@ enum class NodeKind {
     SourceUrl,
     SourcePosition,
 
+    ExternalLink,
+
     /**
      * A note which is rendered once on a page documenting a group of overloaded functions.
      * Needs to be generated equally on all overloads.
diff --git a/core/src/test/kotlin/format/MarkdownFormatTest.kt b/core/src/test/kotlin/format/MarkdownFormatTest.kt
index 427889c5..f306ac74 100644
--- a/core/src/test/kotlin/format/MarkdownFormatTest.kt
+++ b/core/src/test/kotlin/format/MarkdownFormatTest.kt
@@ -242,6 +242,10 @@ public class MarkdownFormatTest {
         verifyMarkdownNodeByName("receiverParameterTypeBound", "Foo")
     }
 
+    @Test fun jdkLinks() {
+        verifyMarkdownNode("jdkLinks", withKotlinRuntime = true)
+    }
+
     private fun verifyMarkdownPackage(fileName: String, withKotlinRuntime: Boolean = false) {
         verifyOutput("testdata/format/$fileName.kt", ".package.md", withKotlinRuntime = withKotlinRuntime) { model, output ->
             markdownService.appendNodes(tempLocation, output, model.members)
diff --git a/core/testdata/format/exceptionClass.md b/core/testdata/format/exceptionClass.md
index 97160d1c..b3464d6f 100644
--- a/core/testdata/format/exceptionClass.md
+++ b/core/testdata/format/exceptionClass.md
@@ -3,7 +3,7 @@
 
 # MyException
 
-`class MyException : Exception`
+`class MyException : [Exception](http://docs.oracle.com/javase/6/docs/api/java/lang/Exception.html)`
 
 
 
diff --git a/core/testdata/format/exceptionClass.package.md b/core/testdata/format/exceptionClass.package.md
index 608aa8ed..fa220fe7 100644
--- a/core/testdata/format/exceptionClass.package.md
+++ b/core/testdata/format/exceptionClass.package.md
@@ -7,5 +7,5 @@
 ### Exceptions
 
 
-| [MyException](test/-my-exception/index) | `class MyException : Exception` |
+| [MyException](test/-my-exception/index) | `class MyException : [Exception](http://docs.oracle.com/javase/6/docs/api/java/lang/Exception.html)` |
 
diff --git a/core/testdata/format/jdkLinks.kt b/core/testdata/format/jdkLinks.kt
new file mode 100644
index 00000000..d5d719b0
--- /dev/null
+++ b/core/testdata/format/jdkLinks.kt
@@ -0,0 +1,5 @@
+/**
+ * This is a [ClassLoader] and I can get its [ClassLoader.getResource]
+ */
+class C : ClassLoader {
+}
diff --git a/core/testdata/format/jdkLinks.md b/core/testdata/format/jdkLinks.md
new file mode 100644
index 00000000..4f0344b5
--- /dev/null
+++ b/core/testdata/format/jdkLinks.md
@@ -0,0 +1,20 @@
+[test](test/index) / [C](test/-c/index)
+
+
+# C
+
+`class C : [ClassLoader](http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html)`
+
+This is a [ClassLoader](http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html) and I can get its [ClassLoader.getResource](http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String))
+
+
+
+
+### Constructors
+
+
+| [<init>](test/-c/-init-) | `C()`
+This is a [ClassLoader](http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html) and I can get its [ClassLoader.getResource](http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String))
+
+ |
+
diff --git a/core/testdata/format/multipleTypeParameterConstraints.md b/core/testdata/format/multipleTypeParameterConstraints.md
index d6b4e853..537b127a 100644
--- a/core/testdata/format/multipleTypeParameterConstraints.md
+++ b/core/testdata/format/multipleTypeParameterConstraints.md
@@ -3,6 +3,6 @@
 
 # f
 
-`fun <T> f(): Unit where T : Appendable, T : CharSequence`
+`fun <T> f(): Unit where T : [Appendable](http://docs.oracle.com/javase/6/docs/api/java/lang/Appendable.html), T : CharSequence`