Make javadoc pages generation deterministic (#2479)

* Make javadoc pages generation deterministic

* Rename `genericQuery` to avoid confusion with Generics

2 files changed, 105 insertions, 51 deletions

diff --git a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocDeprecatedTest.kt b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocDeprecatedTest.kt
index e2331f58..f301baf6 100644
--- a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocDeprecatedTest.kt
+++ b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocDeprecatedTest.kt
@@ -4,6 +4,7 @@ import org.jetbrains.dokka.javadoc.pages.DeprecatedPage
 import org.jetbrains.dokka.javadoc.renderer.TemplateMap
 import org.junit.jupiter.api.Assertions
 import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
 
 internal class JavadocDeprecatedTest : AbstractJavadocTemplateMapTest() {
 
@@ -68,6 +69,21 @@ internal class JavadocDeprecatedTest : AbstractJavadocTemplateMapTest() {
     }
 
     @Test
+    fun `should be sorted by position`() {
+        testDeprecatedPageTemplateMaps { templateMap ->
+            @Suppress("UNCHECKED_CAST")
+            val contents = (templateMap["sections"] as List<TemplateMap>).map { it["caption"] }
+
+            // maybe some other ordering is required by the javadoc spec
+            // but it has to be deterministic
+            val expected = "Classes, Exceptions, Methods, Constructors, Enums, For Removal"
+            val actual = contents.joinToString(separator = ", ")
+
+            assertEquals(expected, actual)
+        }
+    }
+
+    @Test
     fun `provides correct information for deprecated element`() {
         testDeprecatedPageTemplateMaps { templateMap ->
             val map = templateMap.section("Enums")
diff --git a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocIndexTest.kt b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocIndexTest.kt
index 76c345b0..1fbc21ea 100644
--- a/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocIndexTest.kt
+++ b/plugins/javadoc/src/test/kotlin/org/jetbrains/dokka/javadoc/JavadocIndexTest.kt
@@ -2,14 +2,64 @@ package org.jetbrains.dokka.javadoc
 
 import org.jetbrains.dokka.javadoc.pages.IndexPage
 import org.jetbrains.dokka.javadoc.renderer.TemplateMap
+import org.jetbrains.dokka.links.DRI
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
+import kotlin.test.assertNotNull
 
 internal class JavadocIndexTest : AbstractJavadocTemplateMapTest() {
 
+    private val commonTestQuery = """
+            /src/source0.kt
+            package package0
+            /** 
+            * Documentation for ClassA 
+            */
+            class ClassA {
+                fun a() {}
+                fun b() {}
+                fun c() {}
+            }
+            
+            /src/source1.kt
+            package package1
+            /**
+            * Documentation for ClassB
+            */
+            class ClassB {
+                fun d() {}
+                fun e() {}
+                fun f() {}
+            }
+            
+            /src/source2.kt
+            package package1
+            /**
+            * Documentation for ClassB
+            */
+            class ClassC {
+                fun g() {}
+                fun h() {}
+                fun j() {}
+                
+                class InnerClass {
+                    fun k() {}
+                }
+            }
+
+            /src/source3.kt
+            package package1
+            /**
+            * Documentation for ClassCEnum
+            */
+            enum class ClassCEnum {
+                A, D, E
+            }
+        """.trimIndent()
+
     @Test
     fun `generates correct number of index pages`() {
-        testIndexPages { indexPages ->
+        testIndexPages(commonTestQuery) { indexPages ->
             assertEquals(12, indexPages.size)
         }
     }
@@ -20,14 +70,14 @@ internal class JavadocIndexTest : AbstractJavadocTemplateMapTest() {
         fun hasAdditionalFunction() =
             AnnotationTarget.ANNOTATION_CLASS::class.java.methods.any { it.name == "describeConstable" }
 
-        testIndexPages { indexPages ->
+        testIndexPages(commonTestQuery) { indexPages ->
             assertEquals(if (hasAdditionalFunction()) 41 else 40, indexPages.sumBy { it.elements.size })
         }
     }
 
     @Test
     fun `templateMap for class index`() {
-        testIndexPagesTemplateMaps { templateMaps ->
+        testIndexPagesTemplateMaps(commonTestQuery) { templateMaps ->
             @Suppress("UNCHECKED_CAST")
             val element = (templateMaps[2]["elements"] as List<TemplateMap>)[1]
             assertEquals("../package0/ClassA.html", element["address"])
@@ -41,7 +91,7 @@ internal class JavadocIndexTest : AbstractJavadocTemplateMapTest() {
 
     @Test
     fun `templateMap for enum entry index`() {
-        testIndexPagesTemplateMaps { templateMaps ->
+        testIndexPagesTemplateMaps(commonTestQuery) { templateMaps ->
             @Suppress("UNCHECKED_CAST")
             val element = (templateMaps[0]["elements"] as List<TemplateMap>).last()
             assertEquals("../package1/ClassCEnum.html#A", element["address"])
@@ -55,7 +105,7 @@ internal class JavadocIndexTest : AbstractJavadocTemplateMapTest() {
 
     @Test
     fun `templateMap for function index`() {
-        testIndexPagesTemplateMaps { templateMaps ->
+        testIndexPagesTemplateMaps(commonTestQuery) { templateMaps ->
             @Suppress("UNCHECKED_CAST")
             val element = (templateMaps[0]["elements"] as List<TemplateMap>).first()
             assertEquals("../package0/ClassA.html#a()", element["address"])
@@ -67,61 +117,49 @@ internal class JavadocIndexTest : AbstractJavadocTemplateMapTest() {
         }
     }
 
-    private val query = """
-            /src/source0.kt
-            package package0
-            /** 
-            * Documentation for ClassA 
-            */
-            class ClassA {
-                fun a() {}
-                fun b() {}
-                fun c() {}
-            }
-            
-            /src/source1.kt
-            package package1
-            /**
-            * Documentation for ClassB
-            */
-            class ClassB {
-                fun d() {}
-                fun e() {}
-                fun f() {}
-            }
-            
-            /src/source2.kt
-            package package1
-            /**
-            * Documentation for ClassB
-            */
-            class ClassC {
-                fun g() {}
-                fun h() {}
-                fun j() {}
-                
-                class InnerClass {
-                    fun k() {}
-                }
+    @Test
+    fun `should sort overloaded functions deterministically`() {
+        val query = """
+            /src/overloaded.kt
+            package overloaded
+           
+            class Clazz {
+                fun funName(param: List<String>) {}
+                fun funName(param: String) {}
+                fun funName(param: Map<String>) {}
+                fun funName(param: Int) {}
             }
+        """.trimIndent()
 
-            /src/source3.kt
-            package package1
-            /**
-            * Documentation for ClassCEnum
-            */
-            enum class ClassCEnum {
-                A, D, E
+        testIndexPages(query) { allPages ->
+            val indexPage = allPages.find { it.elements.any { el -> el.getId() == "funName" } }
+            assertNotNull(indexPage) { "Index page with functions not found" }
+
+            val indexElementDRIs = indexPage.elements.map { it.getDRI() }
+            assertEquals(4, indexElementDRIs.size)
+            indexElementDRIs.forEach {
+                assertEquals("overloaded", it.packageName)
+                assertEquals("Clazz", it.classNames)
+                assertEquals("funName", it.callable!!.name)
+                assertEquals(1, it.callable!!.params.size)
             }
-        """.trimIndent()
 
-    private fun testIndexPages(operation: (List<IndexPage>) -> Unit) {
+            assertEquals("[kotlin.String]", indexElementDRIs[0].getParam(0))
+            assertEquals("kotlin.Int", indexElementDRIs[1].getParam(0))
+            assertEquals("kotlin.String", indexElementDRIs[2].getParam(0))
+            assertEquals("kotlin.collections.List[kotlin.String]", indexElementDRIs[3].getParam(0))
+        }
+    }
+
+    private fun DRI.getParam(index: Int) = this.callable!!.params[index].toString()
+
+    private fun testIndexPages(query: String, operation: (List<IndexPage>) -> Unit) {
         testTemplateMapInline(query) {
             operation(allPagesOfType())
         }
     }
 
-    private fun testIndexPagesTemplateMaps(operation: (List<TemplateMap>) -> Unit) =
+    private fun testIndexPagesTemplateMaps(query: String, operation: (List<TemplateMap>) -> Unit) =
         testTemplateMapInline(query) {
             operation(allPagesOfType<IndexPage>().map { it.templateMap })
         }