2 files changed, 29 insertions, 7 deletions
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/utils.kt b/plugins/base/src/main/kotlin/transformers/documentables/utils.kt
index 2a5fbc11..079cebea 100644
--- a/plugins/base/src/main/kotlin/transformers/documentables/utils.kt
+++ b/plugins/base/src/main/kotlin/transformers/documentables/utils.kt
@@ -5,16 +5,26 @@ import org.jetbrains.dokka.model.Documentable
 import org.jetbrains.dokka.model.ExceptionInSupertypes
 import org.jetbrains.dokka.model.properties.WithExtraProperties
 
-fun <T> T.isDeprecated() where T : WithExtraProperties<out Documentable> =
-    deprecatedAnnotation != null
+val <T : WithExtraProperties<out Documentable>> T.isException: Boolean
+    get() = extra[ExceptionInSupertypes] != null
+
 
 val <T> T.deprecatedAnnotation where T : WithExtraProperties<out Documentable>
     get() = extra[Annotations]?.let { annotations ->
         annotations.directAnnotations.values.flatten().firstOrNull {
-            it.dri.toString() == "kotlin/Deprecated///PointingToDeclaration/" ||
-                    it.dri.toString() == "java.lang/Deprecated///PointingToDeclaration/"
+            it.isDeprecated()
         }
     }
 
-val <T : WithExtraProperties<out Documentable>> T.isException: Boolean
-    get() = extra[ExceptionInSupertypes] != null
-\ No newline at end of file
+/**
+ * @return true if [T] has [kotlin.Deprecated] or [java.lang.Deprecated]
+ *         annotation for **any** source set
+ */
+fun <T> T.isDeprecated() where T : WithExtraProperties<out Documentable> = deprecatedAnnotation != null
+
+/**
+ * @return true for [kotlin.Deprecated] and [java.lang.Deprecated]
+ */
+fun Annotations.Annotation.isDeprecated() =
+    (this.dri.packageName == "kotlin" && this.dri.classNames == "Deprecated") ||
+            (this.dri.packageName == "java.lang" && this.dri.classNames == "Deprecated")
diff --git a/plugins/base/src/main/kotlin/transformers/pages/merger/SameMethodNamePageMergerStrategy.kt b/plugins/base/src/main/kotlin/transformers/pages/merger/SameMethodNamePageMergerStrategy.kt
index 003d68cf..87ff14a4 100644
--- a/plugins/base/src/main/kotlin/transformers/pages/merger/SameMethodNamePageMergerStrategy.kt
+++ b/plugins/base/src/main/kotlin/transformers/pages/merger/SameMethodNamePageMergerStrategy.kt
@@ -1,8 +1,11 @@
 package org.jetbrains.dokka.base.transformers.pages.merger
 
 import org.jetbrains.dokka.base.renderers.sourceSets
+import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
 import org.jetbrains.dokka.model.DisplaySourceSet
+import org.jetbrains.dokka.model.Documentable
 import org.jetbrains.dokka.model.dfs
+import org.jetbrains.dokka.model.properties.WithExtraProperties
 import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.utilities.DokkaLogger
 
@@ -12,7 +15,12 @@ import org.jetbrains.dokka.utilities.DokkaLogger
  */
 class SameMethodNamePageMergerStrategy(val logger: DokkaLogger) : PageMergerStrategy {
     override fun tryMerge(pages: List<PageNode>, path: List<String>): List<PageNode> {
-        val members = pages.filterIsInstance<MemberPageNode>().takeIf { it.isNotEmpty() } ?: return pages
+        val members = pages
+            .filterIsInstance<MemberPageNode>()
+            .takeIf { it.isNotEmpty() }
+            ?.sortedBy { it.containsDeprecatedDocumentables() } // non-deprecated first
+            ?: return pages
+
         val name = pages.first().name.also {
             if (pages.any { page -> page.name != it }) { // Is this even possible?
                 logger.error("Page names for $it do not match!")
@@ -33,6 +41,10 @@ class SameMethodNamePageMergerStrategy(val logger: DokkaLogger) : PageMergerStra
         return (pages - members) + listOf(merged)
     }
 
+    @Suppress("UNCHECKED_CAST")
+    private fun MemberPageNode.containsDeprecatedDocumentables() =
+        this.documentables.any { (it as? WithExtraProperties<Documentable>)?.isDeprecated() == true }
+
     private fun List<MemberPageNode>.allSourceSets(): Set<DisplaySourceSet> =
         fold(emptySet()) { acc, e -> acc + e.sourceSets() }