generate signature-based anchors for overloads; use signature instead of name as an anchor for in-page links

13 files changed, 59 insertions, 37 deletions

diff --git a/core/src/main/kotlin/Formats/HtmlFormatService.kt b/core/src/main/kotlin/Formats/HtmlFormatService.kt
index f78439ba..f0d7e6c8 100644
--- a/core/src/main/kotlin/Formats/HtmlFormatService.kt
+++ b/core/src/main/kotlin/Formats/HtmlFormatService.kt
@@ -22,8 +22,9 @@ open class HtmlFormatService @Inject constructor(@Named("folders") locationServi
         return "<span class=\"keyword\">${formatText(text)}</span>"
     }
 
-    override fun formatIdentifier(text: String, kind: IdentifierKind): String {
-        return "<span class=\"identifier\">${formatText(text)}</span>"
+    override fun formatIdentifier(text: String, kind: IdentifierKind, signature: String?): String {
+        val id = signature?.let { " id=\"$it\"" }.orEmpty()
+        return "<span class=\"identifier\"$id>${formatText(text)}</span>"
     }
 
     override fun appendBlockCode(to: StringBuilder, line: String, language: String) {
diff --git a/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt b/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt
index f869bc75..14157cff 100644
--- a/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt
+++ b/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt
@@ -124,7 +124,8 @@ class KotlinWebsiteFormatService @Inject constructor(locationService: LocationSe
         return "<span class=\"keyword\">${formatText(text)}</span>"
     }
 
-    override fun formatIdentifier(text: String, kind: IdentifierKind): String {
+    override fun formatIdentifier(text: String, kind: IdentifierKind, signature: String?): String {
+        val id = signature?.let { " id=\"$it\"" }.orEmpty()
         return "<span class=\"${identifierClassName(kind)}\">${formatText(text)}</span>"
     }
 
diff --git a/core/src/main/kotlin/Formats/MarkdownFormatService.kt b/core/src/main/kotlin/Formats/MarkdownFormatService.kt
index 4e16b1a8..7a93801e 100644
--- a/core/src/main/kotlin/Formats/MarkdownFormatService.kt
+++ b/core/src/main/kotlin/Formats/MarkdownFormatService.kt
@@ -12,20 +12,10 @@ open class MarkdownFormatService
         return items.map { formatLink(it) }.joinToString(" / ")
     }
 
-    override fun formatText(text: String): String {
-        return text.htmlEscape()
-    }
-
-    override fun formatSymbol(text: String): String {
-        return text.htmlEscape()
-    }
-
-    override fun formatKeyword(text: String): String {
-        return text.htmlEscape()
-    }
-    override fun formatIdentifier(text: String, kind: IdentifierKind): String {
-        return text.htmlEscape()
-    }
+    override fun formatText(text: String): String = text.htmlEscape()
+    override fun formatSymbol(text: String): String = text.htmlEscape()
+    override fun formatKeyword(text: String): String = text.htmlEscape()
+    override fun formatIdentifier(text: String, kind: IdentifierKind, signature: String?): String = text.htmlEscape()
 
     override fun formatCode(code: String): String {
         return "`$code`"
diff --git a/core/src/main/kotlin/Formats/StructuredFormatService.kt b/core/src/main/kotlin/Formats/StructuredFormatService.kt
index 1d464396..9221004c 100644
--- a/core/src/main/kotlin/Formats/StructuredFormatService.kt
+++ b/core/src/main/kotlin/Formats/StructuredFormatService.kt
@@ -31,7 +31,7 @@ abstract class StructuredFormatService(locationService: LocationService,
     abstract fun formatText(text: String): String
     abstract fun formatSymbol(text: String): String
     abstract fun formatKeyword(text: String): String
-    abstract fun formatIdentifier(text: String, kind: IdentifierKind): String
+    abstract fun formatIdentifier(text: String, kind: IdentifierKind, signature: String?): String
     fun formatEntity(text: String): String = text
     abstract fun formatLink(text: String, href: String): String
     open fun formatLink(link: FormatLink): String = formatLink(formatText(link.text), link.href)
@@ -60,7 +60,7 @@ abstract class StructuredFormatService(locationService: LocationService,
             is ContentText -> to.append(formatText(content.text))
             is ContentSymbol -> to.append(formatSymbol(content.text))
             is ContentKeyword -> to.append(formatKeyword(content.text))
-            is ContentIdentifier -> to.append(formatIdentifier(content.text, content.kind))
+            is ContentIdentifier -> to.append(formatIdentifier(content.text, content.kind, content.signature))
             is ContentNonBreakingSpace -> to.append(formatNonBreakingSpace())
             is ContentSoftLineBreak -> to.append(formatSoftLineBreak())
             is ContentIndentedSoftLineBreak -> to.append(formatIndentedSoftLineBreak())
@@ -107,7 +107,8 @@ abstract class StructuredFormatService(locationService: LocationService,
     fun locationHref(from: Location, to: DocumentationNode): String {
         val topLevelPage = to.references(RefKind.TopLevelPage).singleOrNull()?.to
         if (topLevelPage != null) {
-            return from.relativePathTo(locationService.location(topLevelPage), to.name)
+            val signature = to.detailOrNull(NodeKind.Signature)
+            return from.relativePathTo(locationService.location(topLevelPage), signature?.name ?: to.name)
         }
         return from.relativePathTo(locationService.location(to))
     }
@@ -180,9 +181,12 @@ abstract class StructuredFormatService(locationService: LocationService,
             }
         }
 
-        private fun formatOverloadGroup(items: MutableList<DocumentationNode>) {
+        private fun formatOverloadGroup(items: List<DocumentationNode>) {
             items.forEach {
                 val rendered = languageService.render(it)
+                it.detailOrNull(NodeKind.Signature)?.let {
+                    appendAnchor(to, it.name)
+                }
                 appendAsSignature(to, rendered) {
                     to.append(formatCode(formatText(location, rendered)))
                     it.appendSourceLink()
diff --git a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt
index 67bf1f08..9d75792c 100644
--- a/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt
+++ b/core/src/main/kotlin/Java/JavaPsiDocumentationBuilder.kt
@@ -6,15 +6,15 @@ import com.intellij.psi.util.InheritanceUtil
 
 fun getSignature(element: PsiElement?) = when(element) {
     is PsiClass -> element.qualifiedName
-    is PsiField -> element.containingClass!!.qualifiedName + "#" + element.name
+    is PsiField -> element.containingClass!!.qualifiedName + "$" + element.name
     is PsiMethod ->
-        element.containingClass!!.qualifiedName + "#" + element.name + "(" +
+        element.containingClass!!.qualifiedName + "$" + element.name + "(" +
                 element.parameterList.parameters.map { it.type.typeSignature() }.joinToString(",") + ")"
     else -> null
 }
 
 private fun PsiType.typeSignature(): String = when(this) {
-    is PsiArrayType -> "Array<${componentType.typeSignature()}>"
+    is PsiArrayType -> "Array((${componentType.typeSignature()}))"
     else -> mapTypeName(this)
 }
 
diff --git a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
index f91f160b..3c4c0c39 100644
--- a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
+++ b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
@@ -227,6 +227,10 @@ class DocumentationBuilder
         appendSourceLink(sourceElement.getPsi(), options.sourceLinks)
     }
 
+    fun DocumentationNode.appendSignature(descriptor: DeclarationDescriptor) {
+        appendTextNode(descriptor.signature(), NodeKind.Signature, RefKind.Detail)
+    }
+
     fun DocumentationNode.appendChild(descriptor: DeclarationDescriptor, kind: RefKind): DocumentationNode? {
         // do not include generated code
         if (descriptor is CallableMemberDescriptor && descriptor.kind != CallableMemberDescriptor.Kind.DECLARATION)
@@ -440,6 +444,7 @@ class DocumentationBuilder
         node.appendAnnotations(this)
         node.appendModifiers(this)
         node.appendSourceLink(source)
+        node.appendSignature(this)
 
         overriddenDescriptors.forEach {
             addOverrideLink(it, this)
@@ -468,6 +473,7 @@ class DocumentationBuilder
         node.appendAnnotations(this)
         node.appendModifiers(this)
         node.appendSourceLink(source)
+        node.appendSignature(this)
         if (isVar) {
             node.appendTextNode("var", NodeKind.Modifier)
         }
@@ -518,6 +524,7 @@ class DocumentationBuilder
         }
         node.appendAnnotations(this)
         node.appendModifiers(this)
+        node.appendSignature(this)
         if (varargElementType != null && node.details(NodeKind.Modifier).none { it.name == "vararg" }) {
             node.appendTextNode("vararg", NodeKind.Modifier)
         }
@@ -699,10 +706,10 @@ fun CallableMemberDescriptor.getExtensionClassDescriptor(): ClassifierDescriptor
 
 fun DeclarationDescriptor.signature(): String = when(this) {
     is ClassDescriptor, is PackageFragmentDescriptor -> DescriptorUtils.getFqName(this).asString()
-    is PropertyDescriptor -> containingDeclaration.signature() + "#" + name + receiverSignature()
-    is FunctionDescriptor -> containingDeclaration.signature() + "#" + name + parameterSignature()
-    is ValueParameterDescriptor -> containingDeclaration.signature() + ":" + name
-    is TypeParameterDescriptor -> containingDeclaration.signature() + "<" + name
+    is PropertyDescriptor -> containingDeclaration.signature() + "$" + name + receiverSignature()
+    is FunctionDescriptor -> containingDeclaration.signature() + "$" + name + parameterSignature()
+    is ValueParameterDescriptor -> containingDeclaration.signature() + "/" + name
+    is TypeParameterDescriptor -> containingDeclaration.signature() + "*" + name
 
     else -> throw UnsupportedOperationException("Don't know how to calculate signature for $this")
 }
@@ -727,7 +734,10 @@ fun CallableMemberDescriptor.parameterSignature(): String {
 fun KotlinType.signature(): String {
     val declarationDescriptor = constructor.declarationDescriptor ?: return "<null>"
     val typeName = DescriptorUtils.getFqName(declarationDescriptor).asString()
-    return typeName + arguments.joinToString(prefix = "<", postfix = ">") { it.type.signature() }
+    if (arguments.isEmpty()) {
+        return typeName
+    }
+    return typeName + arguments.joinToString(prefix = "((", postfix = "))") { it.type.signature() }
 }
 
 fun DeclarationDescriptor.signatureWithSourceLocation(): String {
diff --git a/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt b/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt
index a5bb5ee7..a0d8f95d 100644
--- a/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt
+++ b/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt
@@ -215,7 +215,7 @@ class KotlinLanguageService : LanguageService {
             renderAnnotationsForNode(node)
         }
         renderModifiersForNode(node, renderMode)
-        identifier(node.name, IdentifierKind.ParameterName)
+        identifier(node.name, IdentifierKind.ParameterName, node.detailOrNull(NodeKind.Signature)?.name)
         symbol(":")
         nbsp()
         val parameterType = node.detail(NodeKind.Type)
diff --git a/core/src/main/kotlin/Model/Content.kt b/core/src/main/kotlin/Model/Content.kt
index 4c69f6cb..0a38a524 100644
--- a/core/src/main/kotlin/Model/Content.kt
+++ b/core/src/main/kotlin/Model/Content.kt
@@ -45,7 +45,9 @@ data class ContentKeyword(val text: String) : ContentNode {
         get() = text.length
 }
 
-data class ContentIdentifier(val text: String, val kind: IdentifierKind = IdentifierKind.Other) : ContentNode {
+data class ContentIdentifier(val text: String,
+                             val kind: IdentifierKind = IdentifierKind.Other,
+                             val signature: String? = null) : ContentNode {
     override val textLength: Int
         get() = text.length
 }
@@ -140,7 +142,11 @@ fun content(body: ContentBlock.() -> Unit): ContentBlock {
 fun ContentBlock.text(value: String) = append(ContentText(value))
 fun ContentBlock.keyword(value: String) = append(ContentKeyword(value))
 fun ContentBlock.symbol(value: String) = append(ContentSymbol(value))
-fun ContentBlock.identifier(value: String, kind: IdentifierKind = IdentifierKind.Other) = append(ContentIdentifier(value, kind))
+
+fun ContentBlock.identifier(value: String, kind: IdentifierKind = IdentifierKind.Other, signature: String? = null) {
+    append(ContentIdentifier(value, kind, signature))
+}
+
 fun ContentBlock.nbsp() = append(ContentNonBreakingSpace)
 fun ContentBlock.softLineBreak() = append(ContentSoftLineBreak)
 fun ContentBlock.indentedSoftLineBreak() = append(ContentIndentedSoftLineBreak)
diff --git a/core/src/main/kotlin/Model/DocumentationNode.kt b/core/src/main/kotlin/Model/DocumentationNode.kt
index 3cedb8e6..f7e935b2 100644
--- a/core/src/main/kotlin/Model/DocumentationNode.kt
+++ b/core/src/main/kotlin/Model/DocumentationNode.kt
@@ -42,6 +42,7 @@ enum class NodeKind {
 
     SourceUrl,
     SourcePosition,
+    Signature,
 
     ExternalLink,
 
@@ -115,6 +116,7 @@ open class DocumentationNode(val name: String,
     fun links(kind: NodeKind): List<DocumentationNode> = links.filter { it.kind == kind }
 
     fun detail(kind: NodeKind): DocumentationNode = details.filter { it.kind == kind }.single()
+    fun detailOrNull(kind: NodeKind): DocumentationNode? = details.filter { it.kind == kind }.singleOrNull()
     fun member(kind: NodeKind): DocumentationNode = members.filter { it.kind == kind }.single()
     fun link(kind: NodeKind): DocumentationNode = links.filter { it.kind == kind }.single()
 
diff --git a/core/src/main/kotlin/Model/DocumentationReference.kt b/core/src/main/kotlin/Model/DocumentationReference.kt
index 0b40e83a..0c87d719 100644
--- a/core/src/main/kotlin/Model/DocumentationReference.kt
+++ b/core/src/main/kotlin/Model/DocumentationReference.kt
@@ -1,5 +1,6 @@
 package org.jetbrains.dokka
 
+import com.google.inject.Inject
 import com.google.inject.Singleton
 
 enum class RefKind {
@@ -35,7 +36,8 @@ class PendingDocumentationReference(val lazyNodeFrom: () -> DocumentationNode?,
 }
 
 @Singleton
-class NodeReferenceGraph() {
+class NodeReferenceGraph
+        @Inject constructor(val logger: DokkaLogger) {
     private val nodeMap = hashMapOf<String, DocumentationNode>()
     val references = arrayListOf<PendingDocumentationReference>()
 
@@ -55,7 +57,13 @@ class NodeReferenceGraph() {
         references.add(PendingDocumentationReference({ -> nodeMap[fromSignature]}, { -> nodeMap[toSignature]}, kind))
     }
 
-    fun lookup(signature: String): DocumentationNode? = nodeMap[signature]
+    fun lookup(signature: String): DocumentationNode? {
+        val result = nodeMap[signature]
+        if (result == null) {
+            logger.warn("Can't find node by signature $signature")
+        }
+        return result
+    }
 
     fun resolveReferences() {
         references.forEach { it.resolve() }
diff --git a/core/src/main/kotlin/javadoc/docbase.kt b/core/src/main/kotlin/javadoc/docbase.kt
index 25733464..5ddaa37f 100644
--- a/core/src/main/kotlin/javadoc/docbase.kt
+++ b/core/src/main/kotlin/javadoc/docbase.kt
@@ -366,7 +366,7 @@ class MethodAdapter(module: ModuleNodeAdapter, node: DocumentationNode) : Docume
 class FieldAdapter(module: ModuleNodeAdapter, node: DocumentationNode) : DocumentationNodeAdapter(module, node), ProgramElementDoc by ProgramElementAdapter(module, node), FieldDoc {
     override fun isSynthetic(): Boolean = false
 
-    override fun constantValueExpression(): String? = node.details(NodeKind.Value).firstOrNull()?.let { it.name }
+    override fun constantValueExpression(): String? = node.detailOrNull(NodeKind.Value)?.let { it.name }
     override fun constantValue(): Any? = constantValueExpression()
 
     override fun type(): Type = TypeAdapter(module, node.detail(NodeKind.Type))
diff --git a/core/src/test/kotlin/model/ClassTest.kt b/core/src/test/kotlin/model/ClassTest.kt
index 0a824f1c..d4e6f26b 100644
--- a/core/src/test/kotlin/model/ClassTest.kt
+++ b/core/src/test/kotlin/model/ClassTest.kt
@@ -51,7 +51,7 @@ public class ClassTest {
                         assertEquals("name", name)
                         assertEquals(NodeKind.Parameter, kind)
                         assertEquals(Content.Empty, content)
-                        assertEquals("String", details.single().name)
+                        assertEquals("String", detail(NodeKind.Type).name)
                         assertTrue(links.none())
                         assertTrue(members.none())
                     }
diff --git a/core/src/test/kotlin/model/FunctionTest.kt b/core/src/test/kotlin/model/FunctionTest.kt
index 0a65b640..af85d569 100644
--- a/core/src/test/kotlin/model/FunctionTest.kt
+++ b/core/src/test/kotlin/model/FunctionTest.kt
@@ -130,7 +130,7 @@ Documentation""", content.description.toTestString())
                     assertEquals("x", name)
                     assertEquals(NodeKind.Parameter, kind)
                     assertEquals("parameter", content.summary.toTestString())
-                    assertEquals("Int", details.single().name)
+                    assertEquals("Int", detail(NodeKind.Type).name)
                     assertTrue(members.none())
                     assertTrue(links.none())
                 }