From 50a3323322265ff3b5dab1d861a25bbb1167812a Mon Sep 17 00:00:00 2001
From: Ignat Beresnev <ignat.beresnev@jetbrains.com>
Date: Thu, 18 Aug 2022 19:33:53 +0200
Subject: Add deprecation details block (#2622)

---
 .../src/main/kotlin/renderers/html/HtmlRenderer.kt |   3 +
 .../renderers/html/NavigationDataProvider.kt       |  35 +-
 .../main/kotlin/renderers/html/NavigationPage.kt   |  17 +-
 .../main/kotlin/signatures/JvmSignatureUtils.kt    |   3 +
 .../kotlin/signatures/KotlinSignatureProvider.kt   |  39 +-
 .../main/kotlin/signatures/KotlinSignatureUtils.kt |  15 +-
 .../kotlin/transformers/documentables/utils.kt     |  22 +-
 .../merger/SameMethodNamePageMergerStrategy.kt     |  14 +-
 .../documentables/DefaultPageCreator.kt            |   2 +
 .../documentables/DeprecationSectionCreator.kt     | 190 ++++++++++
 .../documentables/PageContentBuilder.kt            |   4 +
 .../base/src/main/resources/dokka/styles/style.css |  33 ++
 .../annotations/DepredatedAndSinceKotlinTest.kt    | 103 ------
 .../content/annotations/JavaDeprecatedTest.kt      | 139 ++++++++
 .../content/annotations/KotlinDeprecatedTest.kt    | 395 +++++++++++++++++++++
 .../kotlin/content/annotations/SinceKotlinTest.kt  |  61 ++++
 .../test/kotlin/renderers/html/NavigationTest.kt   | 109 +++++-
 plugins/base/src/test/kotlin/utils/contentUtils.kt |   4 +-
 18 files changed, 1046 insertions(+), 142 deletions(-)
 create mode 100644 plugins/base/src/main/kotlin/translators/documentables/DeprecationSectionCreator.kt
 delete mode 100644 plugins/base/src/test/kotlin/content/annotations/DepredatedAndSinceKotlinTest.kt
 create mode 100644 plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
 create mode 100644 plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt
 create mode 100644 plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt

(limited to 'plugins/base/src')

diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
index 945fff38..f5c3854c 100644
--- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt
@@ -95,6 +95,7 @@ open class HtmlRenderer(
                 childrenCallback()
             }
             node.hasStyle(ContentStyle.KDocTag) -> span("kdoc-tag") { childrenCallback() }
+            node.hasStyle(ContentStyle.Footnote) -> div("footnote") { childrenCallback() }
             node.hasStyle(TextStyle.BreakableAfter) -> {
                 span { childrenCallback() }
                 wbr { }
@@ -124,10 +125,12 @@ open class HtmlRenderer(
             node.dci.kind == ContentKind.Cover -> div("cover $additionalClasses") { //TODO this can be removed
                 childrenCallback()
             }
+            node.dci.kind == ContentKind.Deprecation -> div("deprecation-content") { childrenCallback() }
             node.hasStyle(TextStyle.Paragraph) -> p(additionalClasses) { childrenCallback() }
             node.hasStyle(TextStyle.Block) -> div(additionalClasses) { childrenCallback() }
             node.hasStyle(TextStyle.Quotation) -> blockQuote(additionalClasses) { childrenCallback() }
             node.hasStyle(TextStyle.FloatingRight) -> span("clearfix") { span("floating-right") { childrenCallback() } }
+            node.hasStyle(TextStyle.Strikethrough) -> strike { childrenCallback() }
             node.isAnchorable -> buildAnchor(
                 node.anchor!!,
                 node.anchorLabel!!,
diff --git a/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt
index 958488ef..ecce70e8 100644
--- a/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt
@@ -1,6 +1,8 @@
 package org.jetbrains.dokka.base.renderers.html
 
 import org.jetbrains.dokka.base.renderers.sourceSets
+import org.jetbrains.dokka.base.signatures.KotlinSignatureUtils.annotations
+import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
 import org.jetbrains.dokka.base.transformers.documentables.isException
 import org.jetbrains.dokka.base.translators.documentables.DocumentableLanguage
 import org.jetbrains.dokka.base.translators.documentables.documentableLanguage
@@ -17,6 +19,7 @@ abstract class NavigationDataProvider {
             dri = page.dri.first(),
             sourceSets = page.sourceSets(),
             icon = chooseNavigationIcon(page),
+            styles = chooseStyles(page),
             children = page.navigableChildren()
         )
 
@@ -31,8 +34,8 @@ abstract class NavigationDataProvider {
             name
         }
 
-    private fun chooseNavigationIcon(contentPage: ContentPage): NavigationNodeIcon? {
-        return if (contentPage is WithDocumentables) {
+    private fun chooseNavigationIcon(contentPage: ContentPage): NavigationNodeIcon? =
+        if (contentPage is WithDocumentables) {
             val documentable = contentPage.documentables.firstOrNull()
             val isJava = documentable?.hasAnyJavaSources() ?: false
 
@@ -61,27 +64,41 @@ abstract class NavigationDataProvider {
         } else {
             null
         }
-    }
 
     private fun Documentable.hasAnyJavaSources(): Boolean {
         val withSources = this as? WithSources ?: return false
         return this.sourceSets.any { withSources.documentableLanguage(it) == DocumentableLanguage.JAVA }
     }
 
-    private fun DClass.isAbstract(): Boolean {
-        return modifier.values.all { it is KotlinModifier.Abstract || it is JavaModifier.Abstract }
+    private fun DClass.isAbstract() =
+        modifier.values.all { it is KotlinModifier.Abstract || it is JavaModifier.Abstract }
+
+    private fun chooseStyles(page: ContentPage): Set<Style> =
+        if (page.containsOnlyDeprecatedDocumentables()) setOf(TextStyle.Strikethrough) else emptySet()
+
+    private fun ContentPage.containsOnlyDeprecatedDocumentables(): Boolean {
+        if (this !is WithDocumentables) {
+            return false
+        }
+        return this.documentables.isNotEmpty() && this.documentables.all { it.isDeprecatedForAllSourceSets() }
+    }
+
+    private fun Documentable.isDeprecatedForAllSourceSets(): Boolean {
+        val sourceSetAnnotations = this.annotations()
+        return sourceSetAnnotations.isNotEmpty() && sourceSetAnnotations.all { (_, annotations) ->
+            annotations.any { it.isDeprecated() }
+        }
     }
 
-    private fun ContentPage.navigableChildren(): List<NavigationNode> {
-        return if (this is ClasslikePage) {
-            return this.navigableChildren()
+    private fun ContentPage.navigableChildren() =
+        if (this is ClasslikePage) {
+            this.navigableChildren()
         } else {
             children
                 .filterIsInstance<ContentPage>()
                 .map { visit(it) }
                 .sortedBy { it.name.toLowerCase() }
         }
-    }
 
     private fun ClasslikePage.navigableChildren(): List<NavigationNode> {
         // Classlikes should only have other classlikes as navigable children
diff --git a/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt b/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt
index 87808add..fc17983d 100644
--- a/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt
@@ -57,17 +57,27 @@ class NavigationPage(
                             span("nav-link-grid") {
                                 span("nav-link-child ${node.icon?.style()}")
                                 span("nav-link-child") {
-                                    buildBreakableText(node.name)
+                                    nodeText(node)
                                 }
                             }
                         } else {
-                            buildBreakableText(node.name)
+                            nodeText(node)
                         }
                     }
                 }
                 node.children.withIndex().forEach { (n, p) -> visit(p, "$navId-$n", renderer) }
             }
         }
+
+    private fun FlowContent.nodeText(node: NavigationNode) {
+        if (node.styles.contains(TextStyle.Strikethrough)) {
+            strike {
+                buildBreakableText(node.name)
+            }
+        } else {
+            buildBreakableText(node.name)
+        }
+    }
 }
 
 data class NavigationNode(
@@ -75,6 +85,7 @@ data class NavigationNode(
     val dri: DRI,
     val sourceSets: Set<DisplaySourceSet>,
     val icon: NavigationNodeIcon?,
+    val styles: Set<Style> = emptySet(),
     override val children: List<NavigationNode>
 ) : WithChildren<NavigationNode>
 
@@ -108,4 +119,4 @@ fun NavigationPage.transform(block: (NavigationNode) -> NavigationNode) =
     NavigationPage(root.transform(block), moduleName, context)
 
 fun NavigationNode.transform(block: (NavigationNode) -> NavigationNode) =
-    run(block).let { NavigationNode(it.name, it.dri, it.sourceSets, it.icon, it.children.map(block)) }
+    run(block).let { NavigationNode(it.name, it.dri, it.sourceSets, it.icon, it.styles, it.children.map(block)) }
diff --git a/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt b/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt
index dc5a9543..7ed7ff3f 100644
--- a/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt
+++ b/plugins/base/src/main/kotlin/signatures/JvmSignatureUtils.kt
@@ -20,6 +20,9 @@ interface JvmSignatureUtils {
     fun Collection<ExtraModifiers>.toSignatureString(): String =
         joinToString("") { it.name.toLowerCase() + " " }
 
+    @Suppress("UNCHECKED_CAST")
+    fun Documentable.annotations() = (this as? WithExtraProperties<Documentable>)?.annotations() ?: emptyMap()
+
     fun <T : AnnotationTarget> WithExtraProperties<T>.annotations(): SourceSetDependent<List<Annotations.Annotation>> =
         extra[Annotations]?.directAnnotations ?: emptyMap()
 
diff --git a/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt b/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt
index 24ed0765..2692928b 100644
--- a/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt
+++ b/plugins/base/src/main/kotlin/signatures/KotlinSignatureProvider.kt
@@ -72,12 +72,12 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
             contentBuilder.contentFor(
                 e,
                 ContentKind.Symbol,
-                setOf(TextStyle.Monospace) + e.stylesIfDeprecated(it),
+                setOf(TextStyle.Monospace),
                 sourceSets = setOf(it)
             ) {
                 group(styles = setOf(TextStyle.Block)) {
                     annotationsBlock(e)
-                    link(e.name, e.dri, styles = emptySet())
+                    link(e.name, e.dri, styles = mainStyles + e.stylesIfDeprecated(it))
                 }
             }
         }
@@ -91,12 +91,12 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
         return contentBuilder.contentFor(
             c,
             ContentKind.Symbol,
-            setOf(TextStyle.Monospace) + deprecationStyles,
+            setOf(TextStyle.Monospace),
             sourceSets = setOf(sourceSet)
         ) {
             keyword("actual ")
             keyword("typealias ")
-            link(c.name.orEmpty(), c.dri)
+            link(c.name.orEmpty(), c.dri, styles = mainStyles + deprecationStyles)
             operator(" = ")
             signatureForProjection(aliasedType)
         }
@@ -142,7 +142,7 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
         return contentBuilder.contentFor(
             c,
             ContentKind.Symbol,
-            setOf(TextStyle.Monospace) + deprecationStyles,
+            setOf(TextStyle.Monospace),
             sourceSets = setOf(sourceSet)
         ) {
             annotationsBlock(c)
@@ -183,7 +183,7 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
                     keyword("annotation class ")
                 }
             }
-            link(c.name!!, c.dri)
+            link(c.name!!, c.dri, styles = mainStyles + deprecationStyles)
             if (c is WithGenerics) {
                 list(c.generics, prefix = "<", suffix = ">",
                     separatorStyles = mainStyles + TokenStyle.Punctuation,
@@ -251,7 +251,7 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
             contentBuilder.contentFor(
                 p,
                 ContentKind.Symbol,
-                setOf(TextStyle.Monospace) + p.stylesIfDeprecated(sourceSet),
+                setOf(TextStyle.Monospace),
                 sourceSets = setOf(sourceSet)
             ) {
                 annotationsBlock(p)
@@ -272,7 +272,7 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
                     signatureForProjection(it.type)
                     punctuation(".")
                 }
-                link(p.name, p.dri)
+                link(p.name, p.dri, styles = mainStyles + p.stylesIfDeprecated(sourceSet))
                 operator(": ")
                 signatureForProjection(p.type)
                 defaultValueAssign(p, sourceSet)
@@ -298,7 +298,7 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
             contentBuilder.contentFor(
                 f,
                 ContentKind.Symbol,
-                setOf(TextStyle.Monospace) + f.stylesIfDeprecated(sourceSet),
+                setOf(TextStyle.Monospace),
                 sourceSets = setOf(sourceSet)
             ) {
                 annotationsBlock(f)
@@ -320,7 +320,7 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
                     signatureForProjection(it.type)
                     punctuation(".")
                 }
-                link(f.name, f.dri, styles = mainStyles + TokenStyle.Function)
+                link(f.name, f.dri, styles = mainStyles + TokenStyle.Function + f.stylesIfDeprecated(sourceSet))
 
                 // for a function, opening and closing parentheses must be present
                 // anyway, even if it has no parameters, resulting in `fun test(): R`
@@ -357,14 +357,16 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
                     +contentBuilder.contentFor(
                         t,
                         ContentKind.Symbol,
-                        setOf(TextStyle.Monospace) + t.stylesIfDeprecated(it),
+                        setOf(TextStyle.Monospace),
                         sourceSets = platforms.toSet()
                     ) {
                         annotationsBlock(t)
                         t.visibility[it]?.takeIf { it !in ignoredVisibilities }?.name?.let { keyword("$it ") }
                         processExtraModifiers(t)
                         keyword("typealias ")
-                        signatureForProjection(t.type)
+                        group(styles = mainStyles + t.stylesIfDeprecated(it)) {
+                            signatureForProjection(t.type)
+                        }
                         operator(" = ")
                         signatureForTypealiasTarget(t, type)
                     }
@@ -374,10 +376,15 @@ class KotlinSignatureProvider(ctcc: CommentsToContentConverter, logger: DokkaLog
 
     private fun signature(t: DTypeParameter) =
         t.sourceSets.map {
-            contentBuilder.contentFor(t, styles = t.stylesIfDeprecated(it), sourceSets = setOf(it)) {
-                signatureForProjection(t.variantTypeParameter.withDri(t.dri.withTargetToDeclaration()))
-                list(t.nontrivialBounds, prefix = " : ",
-                surroundingCharactersStyle = mainStyles + TokenStyle.Operator) { bound ->
+            contentBuilder.contentFor(t, sourceSets = setOf(it)) {
+                group(styles = mainStyles + t.stylesIfDeprecated(it)) {
+                    signatureForProjection(t.variantTypeParameter.withDri(t.dri.withTargetToDeclaration()))
+                }
+                list(
+                    elements = t.nontrivialBounds,
+                    prefix = " : ",
+                    surroundingCharactersStyle = mainStyles + TokenStyle.Operator
+                ) { bound ->
                     signatureForProjection(bound)
                 }
             }
diff --git a/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt b/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt
index 381fadf1..ae5275a5 100644
--- a/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt
+++ b/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt
@@ -1,6 +1,8 @@
 package org.jetbrains.dokka.base.signatures
 
 import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder
+import org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinTransformer
+import org.jetbrains.dokka.pages.ContentKind
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.links.DriOfAny
 import org.jetbrains.dokka.links.DriOfUnit
@@ -10,12 +12,21 @@ import org.jetbrains.dokka.model.properties.WithExtraProperties
 
 object KotlinSignatureUtils : JvmSignatureUtils {
 
+    private const val classExtension = "::class"
     private val strategy = OnlyOnce
     private val listBrackets = Pair('[', ']')
-    private val classExtension = "::class"
     private val ignoredAnnotations = setOf(
+        /**
+         * Rendered separately, see [SinceKotlinTransformer]
+         */
         Annotations.Annotation(DRI("kotlin", "SinceKotlin"), emptyMap()),
-        Annotations.Annotation(DRI("kotlin", "Deprecated"), emptyMap())
+
+        /**
+         * Rendered separately as its own block, see usage of [ContentKind.Deprecation]
+         */
+        Annotations.Annotation(DRI("kotlin", "Deprecated"), emptyMap()),
+        Annotations.Annotation(DRI("kotlin", "DeprecatedSinceKotlin"), emptyMap()),
+        Annotations.Annotation(DRI("java.lang", "Deprecated"), emptyMap()), // could be used as well for interop
     )
 
 
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() }
 
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
index f08b2056..de31e448 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
@@ -452,6 +452,8 @@ open class DefaultPageCreator(
         val platforms = d.sourceSets.toSet()
 
         return contentBuilder.contentFor(d, styles = setOf(TextStyle.Block)) {
+            deprecatedSectionContent(d, platforms)
+
             val descriptions = d.descriptions
             if (descriptions.any { it.value.root.children.isNotEmpty() }) {
                 platforms.forEach { platform ->
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DeprecationSectionCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DeprecationSectionCreator.kt
new file mode 100644
index 00000000..73c36d8d
--- /dev/null
+++ b/plugins/base/src/main/kotlin/translators/documentables/DeprecationSectionCreator.kt
@@ -0,0 +1,190 @@
+package org.jetbrains.dokka.base.translators.documentables
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.signatures.KotlinSignatureUtils.annotations
+import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
+import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.pages.ContentKind
+import org.jetbrains.dokka.pages.ContentStyle
+import org.jetbrains.dokka.pages.TextStyle
+import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder
+
+/**
+ * Main header for [Deprecated] section
+ */
+private const val DEPRECATED_HEADER_LEVEL = 3
+
+/**
+ * Header for a direct parameter of [Deprecated] annotation,
+ * such as [Deprecated.message] and [Deprecated.replaceWith]
+ */
+private const val DIRECT_PARAM_HEADER_LEVEL = 4
+
+internal fun PageContentBuilder.DocumentableContentBuilder.deprecatedSectionContent(
+    documentable: Documentable,
+    platforms: Set<DokkaConfiguration.DokkaSourceSet>
+) {
+    val allAnnotations = documentable.annotations()
+    if (allAnnotations.isEmpty()) {
+        return
+    }
+
+    platforms.forEach { platform ->
+        val platformAnnotations = allAnnotations[platform] ?: emptyList()
+        val deprecatedPlatformAnnotations = platformAnnotations.filter { it.isDeprecated() }
+
+        if (deprecatedPlatformAnnotations.isNotEmpty()) {
+            group(kind = ContentKind.Deprecation, sourceSets = setOf(platform), styles = emptySet()) {
+                val kotlinAnnotation = deprecatedPlatformAnnotations.find { it.dri.packageName == "kotlin" }
+                val javaAnnotation = deprecatedPlatformAnnotations.find { it.dri.packageName == "java.lang" }
+
+                // If both annotations are present, priority is given to Kotlin's annotation since it
+                // contains more useful information, and Java's annotation is probably there
+                // for interop with Java callers, so it should be OK to ignore it
+                if (kotlinAnnotation != null) {
+                    createKotlinDeprecatedSectionContent(kotlinAnnotation, platformAnnotations)
+                } else if (javaAnnotation != null) {
+                    createJavaDeprecatedSectionContent(javaAnnotation)
+                }
+            }
+        }
+    }
+}
+
+/**
+ * @see [DeprecatedSinceKotlin]
+ */
+private fun findDeprecatedSinceKotlinAnnotation(annotations: List<Annotations.Annotation>): Annotations.Annotation? {
+    return annotations.firstOrNull {
+        it.dri.packageName == "kotlin" && it.dri.classNames == "DeprecatedSinceKotlin"
+    }
+}
+
+/**
+ * Section with details for Kotlin's [kotlin.Deprecated] annotation
+ */
+private fun DocumentableContentBuilder.createKotlinDeprecatedSectionContent(
+    deprecatedAnnotation: Annotations.Annotation,
+    allAnnotations: List<Annotations.Annotation>
+) {
+    val deprecatedSinceKotlinAnnotation = findDeprecatedSinceKotlinAnnotation(allAnnotations)
+    header(
+        level = DEPRECATED_HEADER_LEVEL,
+        text = createKotlinDeprecatedHeaderText(deprecatedAnnotation, deprecatedSinceKotlinAnnotation)
+    )
+
+    deprecatedSinceKotlinAnnotation?.let {
+        createDeprecatedSinceKotlinFootnoteContent(it)
+    }
+
+    deprecatedAnnotation.takeStringParam("message")?.let {
+        group(styles = setOf(TextStyle.Paragraph)) {
+            text(it)
+        }
+    }
+
+    createReplaceWithSectionContent(deprecatedAnnotation)
+}
+
+private fun createKotlinDeprecatedHeaderText(
+    kotlinDeprecatedAnnotation: Annotations.Annotation,
+    deprecatedSinceKotlinAnnotation: Annotations.Annotation?
+): String {
+    if (deprecatedSinceKotlinAnnotation != null) {
+        // In this case there's no single level, it's dynamic based on api version,
+        // so there should be a footnote with levels and their respective versions
+        return "Deprecated"
+    }
+
+    val deprecationLevel = kotlinDeprecatedAnnotation.params["level"]?.let { (it as? EnumValue)?.enumName }
+    return when (deprecationLevel) {
+        "DeprecationLevel.ERROR" -> "Deprecated (with error)"
+        "DeprecationLevel.HIDDEN" -> "Deprecated (hidden)"
+        else -> "Deprecated"
+    }
+}
+
+/**
+ * Footnote for [DeprecatedSinceKotlin] annotation used in stdlib
+ *
+ * Notice that values are empty by default, so it's not guaranteed that all three will be set
+ */
+private fun DocumentableContentBuilder.createDeprecatedSinceKotlinFootnoteContent(
+    deprecatedSinceKotlinAnnotation: Annotations.Annotation
+) {
+    group(styles = setOf(ContentStyle.Footnote)) {
+        deprecatedSinceKotlinAnnotation.takeStringParam("warningSince")?.let {
+            group(styles = setOf(TextStyle.Paragraph)) {
+                text("Warning since $it")
+            }
+        }
+        deprecatedSinceKotlinAnnotation.takeStringParam("errorSince")?.let {
+            group(styles = setOf(TextStyle.Paragraph)) {
+                text("Error since $it")
+            }
+        }
+        deprecatedSinceKotlinAnnotation.takeStringParam("hiddenSince")?.let {
+            group(styles = setOf(TextStyle.Paragraph)) {
+                text("Hidden since $it")
+            }
+        }
+    }
+}
+
+/**
+ * Section for [ReplaceWith] parameter of [kotlin.Deprecated] annotation
+ */
+private fun DocumentableContentBuilder.createReplaceWithSectionContent(kotlinDeprecatedAnnotation: Annotations.Annotation) {
+    val replaceWithAnnotation = (kotlinDeprecatedAnnotation.params["replaceWith"] as? AnnotationValue)?.annotation
+        ?: return
+
+    header(
+        level = DIRECT_PARAM_HEADER_LEVEL,
+        text = "Replace with"
+    )
+
+    // Signature: vararg val imports: String
+    val imports = (replaceWithAnnotation.params["imports"] as? ArrayValue)
+        ?.value
+        ?.mapNotNull { (it as? StringValue)?.value }
+        ?: emptyList()
+
+    if (imports.isNotEmpty()) {
+        codeBlock(language = "kotlin", styles = setOf(TextStyle.Monospace)) {
+            imports.forEach {
+                text("import $it")
+                breakLine()
+            }
+        }
+    }
+
+    replaceWithAnnotation.takeStringParam("expression")?.removeSurrounding("`")?.let {
+        codeBlock(language = "kotlin", styles = setOf(TextStyle.Monospace)) {
+            text(it)
+        }
+    }
+}
+
+/**
+ * Section with details for Java's [java.lang.Deprecated] annotation
+ */
+private fun DocumentableContentBuilder.createJavaDeprecatedSectionContent(
+    deprecatedAnnotation: Annotations.Annotation,
+) {
+    val isForRemoval = deprecatedAnnotation.takeBooleanParam("forRemoval", default = false)
+    header(
+        level = DEPRECATED_HEADER_LEVEL,
+        text = if (isForRemoval) "Deprecated (for removal)" else "Deprecated"
+    )
+    deprecatedAnnotation.takeStringParam("since")?.let {
+        group(styles = setOf(ContentStyle.Footnote)) {
+            text("Since version $it")
+        }
+    }
+}
+
+private fun Annotations.Annotation.takeBooleanParam(name: String, default: Boolean): Boolean =
+    (this.params[name] as? BooleanValue)?.value ?: default
+
+private fun Annotations.Annotation.takeStringParam(name: String): String? =
+    (this.params[name] as? StringValue)?.takeIf { it.value.isNotEmpty() }?.value
diff --git a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt
index 02b2e0d9..000c955f 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt
@@ -139,6 +139,10 @@ open class PageContentBuilder(
             contents += createText(text, kind, sourceSets, styles, extra)
         }
 
+        fun breakLine(sourceSets: Set<DokkaSourceSet> = mainSourcesetData) {
+            contents += ContentBreakLine(sourceSets.toDisplaySourceSets())
+        }
+
         fun buildSignature(d: Documentable) = signatureProvider.signature(d)
 
         fun table(
diff --git a/plugins/base/src/main/resources/dokka/styles/style.css b/plugins/base/src/main/resources/dokka/styles/style.css
index 8e379c75..0d1085c1 100644
--- a/plugins/base/src/main/resources/dokka/styles/style.css
+++ b/plugins/base/src/main/resources/dokka/styles/style.css
@@ -743,6 +743,39 @@ small {
     font-size: 11px;
 }
 
+.deprecation-content {
+    margin: 20px 10px;
+    border:1px solid var(--border-color);
+    padding: 13px 15px 16px 15px;
+}
+
+.deprecation-content > h3 {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
+.deprecation-content > h4 {
+    font-size: 16px;
+    margin-top: 15px;
+    margin-bottom: 0;
+}
+
+.deprecation-content code.block {
+    padding: 5px 10px;
+    display: inline-block;
+}
+
+.deprecation-content .footnote {
+    margin-left: 25px;
+    font-size: 13px;
+    font-weight: bold;
+    display: block;
+}
+
+.deprecation-content .footnote > p {
+    margin: 0;
+}
+
 .platform-tag {
     display: flex;
     flex-direction: row;
diff --git a/plugins/base/src/test/kotlin/content/annotations/DepredatedAndSinceKotlinTest.kt b/plugins/base/src/test/kotlin/content/annotations/DepredatedAndSinceKotlinTest.kt
deleted file mode 100644
index e0aa1d04..00000000
--- a/plugins/base/src/test/kotlin/content/annotations/DepredatedAndSinceKotlinTest.kt
+++ /dev/null
@@ -1,103 +0,0 @@
-package content.annotations
-
-
-import matchers.content.*
-import org.jetbrains.dokka.pages.ContentPage
-import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
-import org.junit.jupiter.api.Test
-import utils.ParamAttributes
-import utils.bareSignature
-
-
-class DepredatedAndSinceKotlinTest : BaseAbstractTest() {
-
-    private val testConfiguration = dokkaConfiguration {
-        sourceSets {
-            sourceSet {
-                sourceRoots = listOf("src/")
-                analysisPlatform = "jvm"
-            }
-        }
-    }
-
-    @Test
-    fun `function with deprecated annotation`() {
-        testInline(
-            """
-            |/src/main/kotlin/test/source.kt
-            |package test
-            |
-            |@Deprecated("And some things that should not have been forgotten were lost. History became legend. Legend became myth.")
-            |fun ring(abc: String): String {
-            |    return "My precious " + abc
-            |}
-        """.trimIndent(), testConfiguration
-        ) {
-            pagesTransformationStage = { module ->
-                val page = module.children.single { it.name == "test" }
-                    .children.single { it.name == "ring" } as ContentPage
-                page.content.assertNode {
-                    group {
-                        header(1) { +"ring" }
-                    }
-                    divergentGroup {
-                        divergentInstance {
-                            divergent {
-                                bareSignature(
-                                    emptyMap(),
-                                    "",
-                                    "",
-                                    emptySet(),
-                                    "ring",
-                                    "String",
-                                    "abc" to ParamAttributes(emptyMap(), emptySet(), "String")
-                                )
-                            }
-                        }
-                    }
-                }
-            }
-        }
-    }
-
-    @Test
-    fun `function with since kotlin annotation`() {
-        testInline(
-            """
-            |/src/main/kotlin/test/source.kt
-            |package test
-            |
-            |@SinceKotlin("1.3")
-            |fun ring(abc: String): String {
-            |    return "My precious " + abc
-            |}
-        """.trimIndent(), testConfiguration
-        ) {
-            pagesTransformationStage = { module ->
-                val page = module.children.single { it.name == "test" }
-                    .children.single { it.name == "ring" } as ContentPage
-                page.content.assertNode {
-                    group {
-                        header(1) { +"ring" }
-                    }
-                    divergentGroup {
-                        divergentInstance {
-                            divergent {
-                                bareSignature(
-                                    emptyMap(),
-                                    "",
-                                    "",
-                                    emptySet(),
-                                    "ring",
-                                    "String",
-                                    "abc" to ParamAttributes(emptyMap(), emptySet(), "String")
-                                )
-                            }
-                        }
-                    }
-
-                }
-            }
-        }
-    }
-}
diff --git a/plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt b/plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
new file mode 100644
index 00000000..961ce5f5
--- /dev/null
+++ b/plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
@@ -0,0 +1,139 @@
+package content.annotations
+
+import matchers.content.*
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.base.transformers.documentables.deprecatedAnnotation
+import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.pages.ContentPage
+import org.jetbrains.dokka.pages.ContentStyle
+import org.junit.jupiter.api.Test
+import utils.pWrapped
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+class JavaDeprecatedTest : BaseAbstractTest() {
+
+    private val testConfiguration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/")
+                analysisPlatform = "jvm"
+            }
+        }
+    }
+
+    @Test
+    @Suppress("UNCHECKED_CAST")
+    fun `should assert util functions for deprecation`() {
+        testInline(
+            """
+            |/src/main/kotlin/deprecated/DeprecatedJavaClass.java
+            |package deprecated
+            |
+            |@Deprecated(forRemoval = true)
+            |public class DeprecatedJavaClass {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            documentablesTransformationStage = { module ->
+                val deprecatedClass = module.children
+                    .single { it.name == "deprecated" }.children
+                    .single { it.name == "DeprecatedJavaClass" }
+
+                val isDeprecated = (deprecatedClass as WithExtraProperties<out Documentable>).isDeprecated()
+                assertTrue(isDeprecated)
+
+                val deprecatedAnnotation = (deprecatedClass as WithExtraProperties<out Documentable>).deprecatedAnnotation
+                checkNotNull(deprecatedAnnotation)
+
+                assertTrue(deprecatedAnnotation.isDeprecated())
+                assertEquals("java.lang", deprecatedAnnotation.dri.packageName)
+                assertEquals("Deprecated", deprecatedAnnotation.dri.classNames)
+            }
+        }
+    }
+
+    @Test
+    fun `should change deprecated header if marked for removal`() {
+        testInline(
+            """
+            |/src/main/kotlin/deprecated/DeprecatedJavaClass.java
+            |package deprecated
+            |
+            |/**
+            | * Average function description
+            | */
+            |@Deprecated(forRemoval = true)
+            |public class DeprecatedJavaClass {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val deprecatedJavaClass = module.children
+                    .single { it.name == "deprecated" }.children
+                    .single { it.name == "DeprecatedJavaClass" } as ContentPage
+
+                deprecatedJavaClass.content.assertNode {
+                    group {
+                        header(1) { +"DeprecatedJavaClass" }
+                        platformHinted {
+                            skipAllNotMatching()
+                            group {
+                                header(3) {
+                                    +"Deprecated (for removal)"
+                                }
+                            }
+                            group { pWrapped("Average function description") }
+                        }
+                    }
+                    skipAllNotMatching()
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `should add footnote for 'since' param`() {
+        testInline(
+            """
+            |/src/main/kotlin/deprecated/DeprecatedJavaClass.java
+            |package deprecated
+            |
+            |/**
+            | * Average function description
+            | */
+            |@Deprecated(since = "11")
+            |public class DeprecatedJavaClass {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val deprecatedJavaClass = module.children
+                    .single { it.name == "deprecated" }.children
+                    .single { it.name == "DeprecatedJavaClass" } as ContentPage
+
+                deprecatedJavaClass.content.assertNode {
+                    group {
+                        header(1) { +"DeprecatedJavaClass" }
+                        platformHinted {
+                            skipAllNotMatching()
+                            group {
+                                header(3) {
+                                    +"Deprecated"
+                                }
+                                group {
+                                    check { assertEquals(ContentStyle.Footnote, this.style.firstOrNull()) }
+                                    +"Since version 11"
+                                }
+                            }
+                            group { pWrapped("Average function description") }
+                        }
+                    }
+                    skipAllNotMatching()
+                }
+            }
+        }
+    }
+}
diff --git a/plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt b/plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt
new file mode 100644
index 00000000..8b311893
--- /dev/null
+++ b/plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt
@@ -0,0 +1,395 @@
+package content.annotations
+
+import matchers.content.*
+import org.jetbrains.dokka.pages.ContentPage
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.base.transformers.documentables.deprecatedAnnotation
+import org.jetbrains.dokka.pages.ContentStyle
+import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
+import org.jetbrains.dokka.model.Documentable
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.junit.jupiter.api.Test
+import utils.ParamAttributes
+import utils.bareSignature
+import utils.pWrapped
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+
+class KotlinDeprecatedTest : BaseAbstractTest() {
+
+    private val testConfiguration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/")
+                analysisPlatform = "jvm"
+            }
+        }
+    }
+
+    @Test
+    @Suppress("UNCHECKED_CAST")
+    fun `should assert util functions for deprecation`() {
+        testInline(
+            """
+            |/src/main/kotlin/kotlin/KotlinFile.kt
+            |package kotlin
+            |
+            |@Deprecated(
+            |    message = "Fancy message"
+            |)
+            |fun simpleFunction() {} 
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            documentablesTransformationStage = { module ->
+                val deprecatedFunction = module.children
+                    .single { it.name == "kotlin" }.children
+                    .single { it.name == "simpleFunction" }
+
+                val isDeprecated = (deprecatedFunction as WithExtraProperties<out Documentable>).isDeprecated()
+                assertTrue(isDeprecated)
+
+                val deprecatedAnnotation = (deprecatedFunction as WithExtraProperties<out Documentable>).deprecatedAnnotation
+                checkNotNull(deprecatedAnnotation)
+
+                assertTrue(deprecatedAnnotation.isDeprecated())
+                assertEquals("kotlin", deprecatedAnnotation.dri.packageName)
+                assertEquals("Deprecated", deprecatedAnnotation.dri.classNames)
+            }
+        }
+    }
+
+    @Test
+    fun `should change header if deprecation level is not default`() {
+        testInline(
+            """
+            |/src/main/kotlin/kotlin/DeprecatedKotlin.kt
+            |package kotlin
+            |
+            |/**
+            | * Average function description
+            | */
+            |@Deprecated(
+            |    message = "Reason for deprecation bla bla",
+            |    level = DeprecationLevel.ERROR
+            |)
+            |fun oldLegacyFunction(typedParam: SomeOldType, someLiteral: String): String {}
+            |
+            |fun newShinyFunction(typedParam: SomeOldType, someLiteral: String, newTypedParam: SomeNewType): String {}
+            |class SomeOldType {}
+            |class SomeNewType {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val functionWithDeprecatedFunction = module.children
+                    .single { it.name == "kotlin" }.children
+                    .single { it.name == "oldLegacyFunction" } as ContentPage
+
+                functionWithDeprecatedFunction.content.assertNode {
+                    group {
+                        header(1) { +"oldLegacyFunction" }
+                    }
+                    divergentGroup {
+                        divergentInstance {
+                            divergent {
+                                bareSignature(
+                                    annotations = emptyMap(),
+                                    visibility = "",
+                                    modifier = "",
+                                    keywords = emptySet(),
+                                    name = "oldLegacyFunction",
+                                    returnType = "String",
+                                    params = arrayOf(
+                                        "typedParam" to ParamAttributes(emptyMap(), emptySet(), "SomeOldType"),
+                                        "someLiteral" to ParamAttributes(emptyMap(), emptySet(), "String"),
+                                    )
+                                )
+                            }
+                            after {
+                                group {
+                                    header(3) {
+                                        +"Deprecated (with error)"
+                                    }
+                                    p {
+                                        +"Reason for deprecation bla bla"
+                                    }
+                                }
+                                group { pWrapped("Average function description") }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `should display repalceWith param with imports as code blocks`() {
+        testInline(
+            """
+            |/src/main/kotlin/kotlin/DeprecatedKotlin.kt
+            |package kotlin
+            |
+            |/**
+            | * Average function description
+            | */
+            |@Deprecated(
+            |    message = "Reason for deprecation bla bla",
+            |    replaceWith = ReplaceWith(
+            |        "newShinyFunction(typedParam, someLiteral, SomeNewType())",
+            |        imports = [
+            |            "com.example.dokka.debug.newShinyFunction",
+            |            "com.example.dokka.debug.SomeOldType",
+            |            "com.example.dokka.debug.SomeNewType",
+            |        ]
+            |    ),
+            |)
+            |fun oldLegacyFunction(typedParam: SomeOldType, someLiteral: String): String {}
+            |
+            |fun newShinyFunction(typedParam: SomeOldType, someLiteral: String, newTypedParam: SomeNewType): String {}
+            |class SomeOldType {}
+            |class SomeNewType {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val functionWithDeprecatedFunction = module.children
+                    .single { it.name == "kotlin" }.children
+                    .single { it.name == "oldLegacyFunction" } as ContentPage
+
+                functionWithDeprecatedFunction.content.assertNode {
+                    group {
+                        header(1) { +"oldLegacyFunction" }
+                    }
+                    divergentGroup {
+                        divergentInstance {
+                            divergent {
+                                bareSignature(
+                                    annotations = emptyMap(),
+                                    visibility = "",
+                                    modifier = "",
+                                    keywords = emptySet(),
+                                    name = "oldLegacyFunction",
+                                    returnType = "String",
+                                    params = arrayOf(
+                                        "typedParam" to ParamAttributes(emptyMap(), emptySet(), "SomeOldType"),
+                                        "someLiteral" to ParamAttributes(emptyMap(), emptySet(), "String"),
+                                    )
+                                )
+                            }
+                            after {
+                                group {
+                                    header(3) {
+                                        +"Deprecated"
+                                    }
+                                    p {
+                                        +"Reason for deprecation bla bla"
+                                    }
+
+                                    header(4) {
+                                        +"Replace with"
+                                    }
+                                    codeBlock {
+                                        +"import com.example.dokka.debug.newShinyFunction"
+                                        br()
+                                        +"import com.example.dokka.debug.SomeOldType"
+                                        br()
+                                        +"import com.example.dokka.debug.SomeNewType"
+                                        br()
+                                    }
+                                    codeBlock {
+                                        +"newShinyFunction(typedParam, someLiteral, SomeNewType())"
+                                    }
+                                }
+                                group { pWrapped("Average function description") }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `should add footnote for DeprecatedSinceKotlin annotation`() {
+        testInline(
+            """
+            |/src/main/kotlin/kotlin/DeprecatedKotlin.kt
+            |package kotlin
+            |
+            |/**
+            | * Average function description
+            | */
+            |@DeprecatedSinceKotlin(
+            |    warningSince = "1.4",
+            |    errorSince = "1.5",
+            |    hiddenSince = "1.6"
+            |)
+            |@Deprecated(
+            |    message = "Deprecation reason bla bla"
+            |)
+            |fun oldLegacyFunction(typedParam: SomeOldType, someLiteral: String): String {}
+            |
+            |fun newShinyFunction(typedParam: SomeOldType, someLiteral: String, newTypedParam: SomeNewType): String {}
+            |class SomeOldType {}
+            |class SomeNewType {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val functionWithDeprecatedFunction = module.children
+                    .single { it.name == "kotlin" }.children
+                    .single { it.name == "oldLegacyFunction" } as ContentPage
+
+                functionWithDeprecatedFunction.content.assertNode {
+                    group {
+                        header(1) { +"oldLegacyFunction" }
+                    }
+                    divergentGroup {
+                        divergentInstance {
+                            divergent {
+                                bareSignature(
+                                    annotations = emptyMap(),
+                                    visibility = "",
+                                    modifier = "",
+                                    keywords = emptySet(),
+                                    name = "oldLegacyFunction",
+                                    returnType = "String",
+                                    params = arrayOf(
+                                        "typedParam" to ParamAttributes(emptyMap(), emptySet(), "SomeOldType"),
+                                        "someLiteral" to ParamAttributes(emptyMap(), emptySet(), "String"),
+                                    )
+                                )
+                            }
+                            after {
+                                group {
+                                    header(3) {
+                                        +"Deprecated"
+                                    }
+                                    group {
+                                        check { assertEquals(ContentStyle.Footnote, this.style.firstOrNull()) }
+                                        p {
+                                            +"Warning since 1.4"
+                                        }
+                                        p {
+                                            +"Error since 1.5"
+                                        }
+                                        p {
+                                            +"Hidden since 1.6"
+                                        }
+                                    }
+                                    p {
+                                        +"Deprecation reason bla bla"
+                                    }
+                                }
+                                group { pWrapped("Average function description") }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `should generate deprecation block with all parameters present and long description`() {
+        testInline(
+            """
+            |/src/main/kotlin/kotlin/DeprecatedKotlin.kt
+            |package kotlin
+            |
+            |/**
+            | * Average function description
+            | */
+            |@Deprecated(
+            |    message = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas vel vulputate risus. " +
+            |            "Etiam dictum odio vel vulputate auctor.Nulla facilisi. Duis ullamcorper ullamcorper lectus " +
+            |            "nec rutrum. Quisque eu risus eu purus bibendum ultricies. Maecenas tincidunt dui in sodales " +
+            |            "faucibus. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin id sem felis. " +
+            |            "Praesent et libero lacinia, egestas libero in, ultrices lectus. Suspendisse eget volutpat " +
+            |            "velit. Phasellus laoreet mi eu egestas mattis.",
+            |    replaceWith = ReplaceWith(
+            |        "newShinyFunction(typedParam, someLiteral, SomeNewType())",
+            |        imports = [
+            |            "com.example.dokka.debug.newShinyFunction",
+            |            "com.example.dokka.debug.SomeOldType",
+            |            "com.example.dokka.debug.SomeNewType",
+            |        ]
+            |    ),
+            |    level = DeprecationLevel.ERROR
+            |)
+            |fun oldLegacyFunction(typedParam: SomeOldType, someLiteral: String): String {}
+            |
+            |fun newShinyFunction(typedParam: SomeOldType, someLiteral: String, newTypedParam: SomeNewType): String {}
+            |class SomeOldType {}
+            |class SomeNewType {}
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val functionWithDeprecatedFunction = module.children
+                    .single { it.name == "kotlin" }.children
+                    .single { it.name == "oldLegacyFunction" } as ContentPage
+
+                functionWithDeprecatedFunction.content.assertNode {
+                    group {
+                        header(1) { +"oldLegacyFunction" }
+                    }
+                    divergentGroup {
+                        divergentInstance {
+                            divergent {
+                                bareSignature(
+                                    annotations = emptyMap(),
+                                    visibility = "",
+                                    modifier = "",
+                                    keywords = emptySet(),
+                                    name = "oldLegacyFunction",
+                                    returnType = "String",
+                                    params = arrayOf(
+                                        "typedParam" to ParamAttributes(emptyMap(), emptySet(), "SomeOldType"),
+                                        "someLiteral" to ParamAttributes(emptyMap(), emptySet(), "String"),
+                                    )
+                                )
+                            }
+                            after {
+                                group {
+                                    header(3) {
+                                        +"Deprecated (with error)"
+                                    }
+                                    p {
+                                        +("Lorem ipsum dolor sit amet, consectetur adipiscing elit. " +
+                                                "Maecenas vel vulputate risus. Etiam dictum odio vel " +
+                                                "vulputate auctor.Nulla facilisi. Duis ullamcorper " +
+                                                "ullamcorper lectus nec rutrum. Quisque eu risus eu " +
+                                                "purus bibendum ultricies. Maecenas tincidunt dui in sodales faucibus. " +
+                                                "Lorem ipsum dolor sit amet, consectetur adipiscing elit. " +
+                                                "Proin id sem felis. Praesent et libero lacinia, egestas " +
+                                                "libero in, ultrices lectus. Suspendisse eget volutpat velit. " +
+                                                "Phasellus laoreet mi eu egestas mattis.")
+                                    }
+                                    header(4) {
+                                        +"Replace with"
+                                    }
+                                    codeBlock {
+                                        +"import com.example.dokka.debug.newShinyFunction"
+                                        br()
+                                        +"import com.example.dokka.debug.SomeOldType"
+                                        br()
+                                        +"import com.example.dokka.debug.SomeNewType"
+                                        br()
+                                    }
+                                    codeBlock {
+                                        +"newShinyFunction(typedParam, someLiteral, SomeNewType())"
+                                    }
+                                }
+                                group { pWrapped("Average function description") }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
diff --git a/plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt b/plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt
new file mode 100644
index 00000000..84f5b647
--- /dev/null
+++ b/plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt
@@ -0,0 +1,61 @@
+package content.annotations
+
+import matchers.content.*
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.pages.ContentPage
+import org.junit.jupiter.api.Test
+import utils.ParamAttributes
+import utils.bareSignature
+
+class SinceKotlinTest : BaseAbstractTest() {
+
+    private val testConfiguration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/")
+                analysisPlatform = "jvm"
+            }
+        }
+    }
+
+    @Test
+    fun `function with since kotlin annotation`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            |@SinceKotlin("1.3")
+            |fun ring(abc: String): String {
+            |    return "My precious " + abc
+            |}
+        """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" }
+                    .children.single { it.name == "ring" } as ContentPage
+                page.content.assertNode {
+                    group {
+                        header(1) { +"ring" }
+                    }
+                    divergentGroup {
+                        divergentInstance {
+                            divergent {
+                                bareSignature(
+                                    emptyMap(),
+                                    "",
+                                    "",
+                                    emptySet(),
+                                    "ring",
+                                    "String",
+                                    "abc" to ParamAttributes(emptyMap(), emptySet(), "String")
+                                )
+                            }
+                        }
+                    }
+
+                }
+            }
+        }
+    }
+}
diff --git a/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt b/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt
index 104246cb..13a9e711 100644
--- a/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt
+++ b/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt
@@ -7,6 +7,7 @@ import org.junit.jupiter.api.Test
 import utils.TestOutputWriterPlugin
 import kotlin.test.assertEquals
 import utils.navigationHtml
+import kotlin.test.assertNull
 
 class NavigationTest : BaseAbstractTest() {
 
@@ -18,6 +19,106 @@ class NavigationTest : BaseAbstractTest() {
         }
     }
 
+    @Test
+    fun `should strike deprecated class link`() {
+        val writerPlugin = TestOutputWriterPlugin()
+        testInline(
+            """
+            |/src/main/kotlin/com/example/SimpleDeprecatedClass.kt
+            |package com.example
+            |
+            |@Deprecated("reason")
+            |class SimpleDeprecatedClass {}
+            """.trimIndent(),
+            configuration,
+            pluginOverrides = listOf(writerPlugin)
+        ) {
+            renderingStage = { _, _ ->
+                val content = writerPlugin.writer.navigationHtml().select("div.sideMenuPart")
+                assertEquals(3, content.size)
+
+                // Navigation menu should be the following:
+                // - root
+                //    - com.example
+                //       - SimpleDeprecatedClass
+
+                content[0].assertNavigationLink(
+                    id = "root-nav-submenu",
+                    text = "root",
+                    address = "index.html",
+                )
+
+                content[1].assertNavigationLink(
+                    id = "root-nav-submenu-0",
+                    text = "com.example",
+                    address = "root/com.example/index.html",
+                )
+
+                content[2].assertNavigationLink(
+                    id = "root-nav-submenu-0-0",
+                    text = "SimpleDeprecatedClass",
+                    address = "root/com.example/-simple-deprecated-class/index.html",
+                    icon = NavigationNodeIcon.CLASS_KT,
+                    isStrikethrough = true
+                )
+            }
+        }
+    }
+
+    @Test
+    fun `should not strike pages where only one of N documentables is deprecated`() {
+        val writerPlugin = TestOutputWriterPlugin()
+        testInline(
+            """
+            |/src/main/kotlin/com/example/File.kt
+            |package com.example
+            |
+            |/**
+            | * First
+            | */
+            |@Deprecated("reason")
+            |fun functionWithCommonName()
+            |
+            |/**
+            | * Second
+            | */
+            |fun functionWithCommonName()
+            """.trimIndent(),
+            configuration,
+            pluginOverrides = listOf(writerPlugin)
+        ) {
+            renderingStage = { _, _ ->
+                val content = writerPlugin.writer.navigationHtml().select("div.sideMenuPart")
+                assertEquals(3, content.size)
+
+                // Navigation menu should be the following:
+                // - root
+                //    - com.example
+                //       - functionWithCommonName
+
+                content[0].assertNavigationLink(
+                    id = "root-nav-submenu",
+                    text = "root",
+                    address = "index.html",
+                )
+
+                content[1].assertNavigationLink(
+                    id = "root-nav-submenu-0",
+                    text = "com.example",
+                    address = "root/com.example/index.html",
+                )
+
+                content[2].assertNavigationLink(
+                    id = "root-nav-submenu-0-0",
+                    text = "functionWithCommonName()",
+                    address = "root/com.example/function-with-common-name.html",
+                    icon = NavigationNodeIcon.FUNCTION,
+                    isStrikethrough = false
+                )
+            }
+        }
+    }
+
     @Test
     fun `should have expandable classlikes`() {
         val writerPlugin = TestOutputWriterPlugin()
@@ -209,7 +310,7 @@ class NavigationTest : BaseAbstractTest() {
     }
 
     private fun Element.assertNavigationLink(
-        id: String, text: String, address: String, icon: NavigationNodeIcon? = null
+        id: String, text: String, address: String, icon: NavigationNodeIcon? = null, isStrikethrough: Boolean = false
     ) {
         assertEquals(id, this.id())
 
@@ -224,5 +325,11 @@ class NavigationTest : BaseAbstractTest() {
             assertEquals("nav-link-child", iconStyles[0])
             assertEquals(icon.style(), "${iconStyles[1]} ${iconStyles[2]}")
         }
+        if (isStrikethrough) {
+            val textInsideStrikethrough = link.selectFirst("strike")?.text()
+            assertEquals(text, textInsideStrikethrough)
+        } else {
+            assertNull(link.selectFirst("strike"))
+        }
     }
 }
diff --git a/plugins/base/src/test/kotlin/utils/contentUtils.kt b/plugins/base/src/test/kotlin/utils/contentUtils.kt
index 0af253df..08ddf034 100644
--- a/plugins/base/src/test/kotlin/utils/contentUtils.kt
+++ b/plugins/base/src/test/kotlin/utils/contentUtils.kt
@@ -208,7 +208,9 @@ fun ContentMatcherBuilder<*>.typealiasSignature(name: String, expressionTarget:
                                         group {
                                             +"typealias "
                                             group {
-                                                link { +name }
+                                                group {
+                                                    link { +name }
+                                                }
                                                 skipAllNotMatching()
                                             }
                                             +" = "
-- 
cgit