[backport] KT-24271: Support external link resolution in JavadocParser

Original: ace3914

2 files changed, 46 insertions, 15 deletions

diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt
index 646096e5..8b30a6b4 100644
--- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt
+++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt
@@ -45,10 +45,16 @@ class JavaPsiDocumentationBuilder : JavaDocumentationBuilder {
     private val refGraph: NodeReferenceGraph
     private val docParser: JavaDocumentationParser
 
-    @Inject constructor(options: DocumentationOptions, refGraph: NodeReferenceGraph, logger: DokkaLogger, signatureProvider: ElementSignatureProvider) {
+    @Inject constructor(
+            options: DocumentationOptions,
+            refGraph: NodeReferenceGraph,
+            logger: DokkaLogger,
+            signatureProvider: ElementSignatureProvider,
+            externalDocumentationLinkResolver: ExternalDocumentationLinkResolver
+    ) {
         this.options = options
         this.refGraph = refGraph
-        this.docParser = JavadocParser(refGraph, logger, signatureProvider)
+        this.docParser = JavadocParser(refGraph, logger, signatureProvider, externalDocumentationLinkResolver)
     }
 
     constructor(options: DocumentationOptions, refGraph: NodeReferenceGraph, docParser: JavaDocumentationParser) {
diff --git a/core/src/main/kotlin/Java/JavadocParser.kt b/core/src/main/kotlin/Java/JavadocParser.kt
index 5e23e357..e1b15cb2 100644
--- a/core/src/main/kotlin/Java/JavadocParser.kt
+++ b/core/src/main/kotlin/Java/JavadocParser.kt
@@ -26,7 +26,8 @@ interface JavaDocumentationParser {
 class JavadocParser(
     private val refGraph: NodeReferenceGraph,
     private val logger: DokkaLogger,
-    private val signatureProvider: ElementSignatureProvider
+    private val signatureProvider: ElementSignatureProvider,
+    private val externalDocumentationLinkResolver: ExternalDocumentationLinkResolver
 ) : JavaDocumentationParser {
 
     private fun ContentSection.appendTypeElement(signature: String, selector: (DocumentationNode) -> DocumentationNode?) {
@@ -197,25 +198,41 @@ class JavadocParser(
     private fun MutableContent.convertSeeTag(tag: PsiDocTag) {
         val linkElement = tag.linkElement() ?: return
         val seeSection = findSectionByTag(ContentTags.SeeAlso) ?: addSection(ContentTags.SeeAlso, null)
-        val linkSignature = resolveLink(tag.referenceElement())
+
+        val valueElement = tag.referenceElement()
+        val externalLink = resolveExternalLink(valueElement)
         val text = ContentText(linkElement.text)
-        if (linkSignature != null) {
-            val linkNode =
-                ContentNodeLazyLink((tag.valueElement ?: linkElement).text, { -> refGraph.lookupOrWarn(linkSignature, logger) })
-            linkNode.append(text)
-            seeSection.append(linkNode)
-        } else {
-            seeSection.append(text)
+
+        val linkSignature by lazy { resolveInternalLink(valueElement) }
+        val node = when {
+            externalLink != null -> {
+                val linkNode = ContentExternalLink(externalLink)
+                linkNode.append(text)
+                linkNode
+            }
+            linkSignature != null -> {
+                val linkNode =
+                        ContentNodeLazyLink(
+                                (tag.valueElement ?: linkElement).text,
+                                { -> refGraph.lookupOrWarn(linkSignature, logger) }
+                        )
+                linkNode.append(text)
+                linkNode
+            }
+            else -> text
         }
+        seeSection.append(node)
     }
 
     private fun convertInlineDocTag(tag: PsiInlineDocTag, element: PsiNamedElement) = when (tag.name) {
         "link", "linkplain" -> {
             val valueElement = tag.referenceElement()
-            val linkSignature = resolveLink(valueElement)
-            if (linkSignature != null) {
+            val externalLink = resolveExternalLink(valueElement)
+            val linkSignature by lazy { resolveInternalLink(valueElement) }
+            if (externalLink != null || linkSignature != null) {
                 val labelText = tag.dataElements.firstOrNull { it is PsiDocToken }?.text ?: valueElement!!.text
-                val link = "<a docref=\"$linkSignature\">${labelText.htmlEscape()}</a>"
+                val linkTarget = if (externalLink != null) "href=\"$externalLink\"" else "docref=\"$linkSignature\""
+                val link = "<a $linkTarget>${labelText.htmlEscape()}</a>"
                 if (tag.name == "link") "<code>$link</code>" else link
             } else if (valueElement != null) {
                 valueElement.text
@@ -256,7 +273,15 @@ class JavadocParser(
     private fun PsiDocTag.linkElement(): PsiElement? =
         valueElement ?: dataElements.firstOrNull { it !is PsiWhiteSpace }
 
-    private fun resolveLink(valueElement: PsiElement?): String? {
+    private fun resolveExternalLink(valueElement: PsiElement?): String? {
+        val target = valueElement?.reference?.resolve()
+        if (target != null) {
+            return externalDocumentationLinkResolver.buildExternalDocumentationLink(target)
+        }
+        return null
+    }
+
+    private fun resolveInternalLink(valueElement: PsiElement?): String? {
         val target = valueElement?.reference?.resolve()
         if (target != null) {
             return signatureProvider.signature(target)