KT-14818 Render function type argument names in generated documentation (#116)

Fix for KT-14818 Render function type argument names in generated documentation

* Fixup, unescape name, before passing to identifier

* Fixup

8 files changed, 92 insertions, 6 deletions

diff --git a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
index f922a25b..afb95fe6 100644
--- a/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
+++ b/core/src/main/kotlin/Kotlin/DocumentationBuilder.kt
@@ -197,11 +197,15 @@ class DocumentationBuilder
             DescriptorUtils.getFqName(this).asString() in boringBuiltinClasses
 
     fun DocumentationNode.appendAnnotations(annotated: Annotated) {
-        annotated.annotations.filter { it.isDocumented() }.forEach {
-            val annotationNode = it.build()
-            if (annotationNode != null) {
-                append(annotationNode,
-                        if (annotationNode.isDeprecation()) RefKind.Deprecation else RefKind.Annotation)
+        annotated.annotations.forEach {
+            it.build()?.let { annotationNode ->
+                val refKind = when {
+                    it.isDocumented() && annotationNode.isDeprecation() -> RefKind.Deprecation
+                    it.isDocumented() -> RefKind.Annotation
+                    it.isHiddenInDocumentation() -> RefKind.HiddenAnnotation
+                    else -> return@forEach
+                }
+                append(annotationNode, refKind)
             }
         }
     }
@@ -687,10 +691,17 @@ class KotlinJavaDocumentationBuilder
     }
 }
 
+private val hiddenAnnotations = setOf(
+        KotlinBuiltIns.FQ_NAMES.parameterName.asString()
+)
+
+private fun AnnotationDescriptor.isHiddenInDocumentation() =
+        type.constructor.declarationDescriptor?.fqNameSafe?.asString() in hiddenAnnotations
+
 private fun AnnotationDescriptor.isDocumented(): Boolean {
     if (source.getPsi() != null && mustBeDocumented()) return true
     val annotationClassName = type.constructor.declarationDescriptor?.fqNameSafe?.asString()
-    return annotationClassName == "kotlin.ExtensionFunctionType"
+    return annotationClassName == KotlinBuiltIns.FQ_NAMES.extensionFunctionType.asString()
 }
 
 fun AnnotationDescriptor.mustBeDocumented(): Boolean {
diff --git a/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt b/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt
index 6fcf3772..75a8a948 100644
--- a/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt
+++ b/core/src/main/kotlin/Kotlin/KotlinLanguageService.kt
@@ -141,6 +141,16 @@ class KotlinLanguageService : LanguageService {
             }
     }
 
+    private fun ContentBlock.renderFunctionalTypeParameterName(node: DocumentationNode, renderMode: RenderMode) {
+        node.references(RefKind.HiddenAnnotation).map { it.to }
+                .find { it.name == "ParameterName" }?.let {
+            val parameterNameValue = it.detail(NodeKind.Parameter).detail(NodeKind.Value)
+            identifier(parameterNameValue.name.removeSurrounding("\""), IdentifierKind.ParameterName)
+            symbol(":")
+            nbsp()
+        }
+    }
+
     private fun ContentBlock.renderType(node: DocumentationNode, renderMode: RenderMode) {
         var typeArguments = node.details(NodeKind.Type)
         if (node.name == "Function${typeArguments.count() - 1}") {
@@ -153,6 +163,7 @@ class KotlinLanguageService : LanguageService {
             }
             symbol("(")
             renderList(typeArguments.take(typeArguments.size - 1), noWrap = true) {
+                renderFunctionalTypeParameterName(it, renderMode)
                 renderType(it, renderMode)
             }
             symbol(")")
diff --git a/core/src/main/kotlin/Model/DocumentationReference.kt b/core/src/main/kotlin/Model/DocumentationReference.kt
index 0c87d719..0165b567 100644
--- a/core/src/main/kotlin/Model/DocumentationReference.kt
+++ b/core/src/main/kotlin/Model/DocumentationReference.kt
@@ -16,6 +16,7 @@ enum class RefKind {
     Superclass,
     Override,
     Annotation,
+    HiddenAnnotation,
     Deprecation,
     TopLevelPage
 }
diff --git a/core/src/test/kotlin/format/HtmlFormatTest.kt b/core/src/test/kotlin/format/HtmlFormatTest.kt
index 12df7c44..4b4eff59 100644
--- a/core/src/test/kotlin/format/HtmlFormatTest.kt
+++ b/core/src/test/kotlin/format/HtmlFormatTest.kt
@@ -134,6 +134,10 @@ class HtmlFormatTest {
         verifyHtmlNode("linkWithStarProjection", withKotlinRuntime = true)
     }
 
+    @Test fun functionalTypeWithNamedParameters() {
+        verifyHtmlNode("functionalTypeWithNamedParameters")
+    }
+
     private fun verifyHtmlNode(fileName: String, withKotlinRuntime: Boolean = false) {
         verifyHtmlNodes(fileName, withKotlinRuntime) { model -> model.members.single().members }
     }
diff --git a/core/src/test/kotlin/format/MarkdownFormatTest.kt b/core/src/test/kotlin/format/MarkdownFormatTest.kt
index 6e4c44c8..c425e3f6 100644
--- a/core/src/test/kotlin/format/MarkdownFormatTest.kt
+++ b/core/src/test/kotlin/format/MarkdownFormatTest.kt
@@ -227,6 +227,10 @@ class MarkdownFormatTest {
         verifyMarkdownNodeByName("qualifiedNameLink", "foo", withKotlinRuntime = true)
     }
 
+    @Test fun functionalTypeWithNamedParameters() {
+        verifyMarkdownNode("functionalTypeWithNamedParameters")
+    }
+
     @Test fun typeAliases() {
         verifyMarkdownNode("typeAliases")
         verifyMarkdownPackage("typeAliases")
diff --git a/core/testdata/format/functionalTypeWithNamedParameters.html b/core/testdata/format/functionalTypeWithNamedParameters.html
new file mode 100644
index 00000000..84a489ff
--- /dev/null
+++ b/core/testdata/format/functionalTypeWithNamedParameters.html
@@ -0,0 +1,25 @@
+<HTML>
+<HEAD>
+<meta charset="UTF-8">
+</HEAD>
+<BODY>
+<a href="test/index">test</a>&nbsp;/&nbsp;<a href="test/-a/index">A</a><br/>
+<br/>
+<h1>A</h1>
+<code><span class="keyword">class </span><span class="identifier">A</span></code><a href="test/index">test</a>&nbsp;/&nbsp;<a href="test/-b/index">B</a><br/>
+<br/>
+<h1>B</h1>
+<code><span class="keyword">class </span><span class="identifier">B</span></code><a href="test/index">test</a>&nbsp;/&nbsp;<a href="test/-c/index">C</a><br/>
+<br/>
+<h1>C</h1>
+<code><span class="keyword">class </span><span class="identifier">C</span></code><a href="test/index">test</a>&nbsp;/&nbsp;<a href="test/f">f</a><br/>
+<br/>
+<h1>f</h1>
+<a name="$f"></a>
+<code><span class="keyword">val </span><span class="identifier">f</span><span class="symbol">: </span><span class="symbol">(</span><span class="identifier">a</span><span class="symbol">:</span>&nbsp;<a href="test/-a/index"><span class="identifier">A</span></a><span class="symbol">,</span>&nbsp;<span class="identifier">b</span><span class="symbol">:</span>&nbsp;<a href="test/-b/index"><span class="identifier">B</span></a><span class="symbol">)</span>&nbsp;<span class="symbol">-&gt;</span>&nbsp;<a href="test/-c/index"><span class="identifier">C</span></a></code><a href="test/index">test</a>&nbsp;/&nbsp;<a href="test/accept-function-type-with-named-arguments">acceptFunctionTypeWithNamedArguments</a><br/>
+<br/>
+<h1>acceptFunctionTypeWithNamedArguments</h1>
+<a name="$acceptFunctionTypeWithNamedArguments(kotlin.Function2((B, A, C)))"></a>
+<code><span class="keyword">fun </span><span class="identifier">acceptFunctionTypeWithNamedArguments</span><span class="symbol">(</span><span class="identifier" id="$acceptFunctionTypeWithNamedArguments(kotlin.Function2((B, A, C)))/f">f</span><span class="symbol">:</span>&nbsp;<span class="symbol">(</span><span class="identifier">bb</span><span class="symbol">:</span>&nbsp;<a href="test/-b/index"><span class="identifier">B</span></a><span class="symbol">,</span>&nbsp;<span class="identifier">aa</span><span class="symbol">:</span>&nbsp;<a href="test/-a/index"><span class="identifier">A</span></a><span class="symbol">)</span>&nbsp;<span class="symbol">-&gt;</span>&nbsp;<a href="test/-c/index"><span class="identifier">C</span></a><span class="symbol">)</span><span class="symbol">: </span><span class="identifier">Unit</span></code>
+</BODY>
+</HTML>
diff --git a/core/testdata/format/functionalTypeWithNamedParameters.kt b/core/testdata/format/functionalTypeWithNamedParameters.kt
new file mode 100644
index 00000000..3dada27a
--- /dev/null
+++ b/core/testdata/format/functionalTypeWithNamedParameters.kt
@@ -0,0 +1,9 @@
+class A
+class B
+class C
+
+val f: (a: A, b: B) -> C = { a, b -> C() }
+
+fun acceptFunctionTypeWithNamedArguments(f: (bb: B, aa: A) -> C) {
+
+}
\ No newline at end of file
diff --git a/core/testdata/format/functionalTypeWithNamedParameters.md b/core/testdata/format/functionalTypeWithNamedParameters.md
new file mode 100644
index 00000000..317fa6af
--- /dev/null
+++ b/core/testdata/format/functionalTypeWithNamedParameters.md
@@ -0,0 +1,21 @@
+[test](test/index) / [A](test/-a/index)
+
+# A
+
+`class A`[test](test/index) / [B](test/-b/index)
+
+# B
+
+`class B`[test](test/index) / [C](test/-c/index)
+
+# C
+
+`class C`[test](test/index) / [f](test/f)
+
+# f
+
+`val f: (a: `[`A`](test/-a/index)`, b: `[`B`](test/-b/index)`) -> `[`C`](test/-c/index)[test](test/index) / [acceptFunctionTypeWithNamedArguments](test/accept-function-type-with-named-arguments)
+
+# acceptFunctionTypeWithNamedArguments
+
+`fun acceptFunctionTypeWithNamedArguments(f: (bb: `[`B`](test/-b/index)`, aa: `[`A`](test/-a/index)`) -> `[`C`](test/-c/index)`): Unit`
\ No newline at end of file