From 88d36234b710f2ef50db9d874e25fd2378f430ac Mon Sep 17 00:00:00 2001
From: Ignat Beresnev <ignat.beresnev@jetbrains.com>
Date: Thu, 5 May 2022 20:16:05 +0300
Subject: Make javadoc pages generation deterministic (#2479)

* Make javadoc pages generation deterministic

* Rename `genericQuery` to avoid confusion with Generics
---
 .../dokka/javadoc/pages/JavadocPageNodes.kt        | 10 ++++----
 .../dokka/javadoc/pages/htmlPreprocessors.kt       | 27 +++++++++++++++++++---
 .../JavadocContentToTemplateMapTranslator.kt       |  2 +-
 3 files changed, 31 insertions(+), 8 deletions(-)

(limited to 'plugins/javadoc/src/main/kotlin/org/jetbrains')

diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
index 6c7691cd..cafc6c3e 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/JavadocPageNodes.kt
@@ -317,17 +317,19 @@ class DeprecatedNode(val name: String, val address: DRI, val description: List<C
     override fun hashCode(): Int = address.hashCode()
 }
 
-enum class DeprecatedPageSection(val id: String, val caption: String, val header: String, val priority: Int = 100) {
-    DeprecatedForRemoval("forRemoval", "For Removal", "Element", priority = 90),
+enum class DeprecatedPageSection(val id: String, val caption: String, val header: String) {
     DeprecatedModules("module", "Modules", "Module"),
     DeprecatedInterfaces("interface", "Interfaces", "Interface"),
     DeprecatedClasses("class", "Classes", "Class"),
-    DeprecatedEnums("enum", "Enums", "Enum"),
     DeprecatedExceptions("exception", "Exceptions", "Exceptions"),
     DeprecatedFields("field", "Fields", "Field"),
     DeprecatedMethods("method", "Methods", "Method"),
     DeprecatedConstructors("constructor", "Constructors", "Constructor"),
-    DeprecatedEnumConstants("enum.constant", "Enum Constants", "Enum Constant")
+    DeprecatedEnums("enum", "Enums", "Enum"),
+    DeprecatedEnumConstants("enum.constant", "Enum Constants", "Enum Constant"),
+    DeprecatedForRemoval("forRemoval", "For Removal", "Element");
+
+    internal fun getPosition() = ordinal
 }
 
 class IndexPage(
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/htmlPreprocessors.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/htmlPreprocessors.kt
index 057b9e85..4438e7e9 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/htmlPreprocessors.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/pages/htmlPreprocessors.kt
@@ -90,9 +90,30 @@ object IndexGenerator : PageTransformer {
         }
         val keys = elements.keys.sortedBy { it }
         val sortedElements = elements.entries.sortedBy { (a, _) -> a }
-        return input.modified(children = input.children + sortedElements.mapIndexed { i, (_, set) ->
-            IndexPage(i + 1, set.sortedBy { it.getId().toLowerCase() }, keys, input.sourceSets())
-        })
+
+        val indexNodeComparator = compareBy<NavigableJavadocNode> { it.getId().toLowerCase() }
+            .thenBy { it.getFullComparatorKey() }
+
+        val indexPages = sortedElements.mapIndexed { idx, (_, set) ->
+            IndexPage(
+                id = idx + 1,
+                elements = set.sortedWith(indexNodeComparator),
+                keys = keys,
+                sourceSet = input.sourceSets()
+            )
+        }
+        return input.modified(children = input.children + indexPages)
+    }
+
+    private fun NavigableJavadocNode.getFullComparatorKey(): String {
+        return getDRI().let { dri ->
+            val packageName = dri.packageName.orEmpty()
+            val className = dri.classNames.orEmpty()
+            val callableName = dri.callable?.name.orEmpty()
+            val parameters = dri.callable?.signature().orEmpty()
+
+            "$packageName/$className/$callableName/$parameters"
+        }
     }
 }
 
diff --git a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
index a6eda405..45fa3f2e 100644
--- a/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
+++ b/plugins/javadoc/src/main/kotlin/org/jetbrains/dokka/javadoc/renderer/JavadocContentToTemplateMapTranslator.kt
@@ -81,7 +81,7 @@ internal class JavadocContentToTemplateMapTranslator(
                 "id" to node.name,
                 "title" to "Deprecated",
                 "kind" to "deprecated",
-                "sections" to node.elements.toList().sortedBy { (section, _) -> section.priority }
+                "sections" to node.elements.toList().sortedBy { (section, _) -> section.getPosition() }
                     .map { (s, e) -> templateMapForDeprecatedPageSection(s, e) }
             )
 
-- 
cgit