Restructure the project to utilize included builds (#3174)

* Refactor and simplify artifact publishing
* Update Gradle to 8.4
* Refactor and simplify convention plugins and build scripts

Fixes #3132

---------

Co-authored-by: Adam <897017+aSemy@users.noreply.github.com>
Co-authored-by: Oleg Yukhnevich <whyoleg@gmail.com>

5 files changed, 1361 insertions, 0 deletions

diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/ContentForAnnotationsTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/ContentForAnnotationsTest.kt
new file mode 100644
index 00000000..7293b53c
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/ContentForAnnotationsTest.kt
@@ -0,0 +1,351 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package content.annotations
+
+import matchers.content.*
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.base.utils.firstNotNullOfOrNull
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.pages.ContentPage
+import org.jetbrains.dokka.pages.ContentText
+import org.jetbrains.dokka.pages.MemberPageNode
+import org.jetbrains.dokka.pages.PackagePageNode
+import utils.ParamAttributes
+import utils.assertNotNull
+import utils.bareSignature
+import utils.propertySignature
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+
+class ContentForAnnotationsTest : BaseAbstractTest() {
+
+
+    private val testConfiguration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/")
+                analysisPlatform = "jvm"
+                classpath += jvmStdlibPath!!
+            }
+        }
+    }
+
+    @Test
+    fun `function with documented annotation`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            |@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION,
+            |    AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.EXPRESSION, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FIELD
+            |)
+            |@Retention(AnnotationRetention.SOURCE)
+            |@MustBeDocumented
+            |annotation class Fancy
+            |
+            |
+            |@Fancy
+            |fun function(@Fancy abc: String): String {
+            |    return "Hello, " + abc
+            |}
+        """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" }
+                    .children.single { it.name == "function" } as ContentPage
+                page.content.assertNode {
+                    group {
+                        header(1) { +"function" }
+                    }
+                    divergentGroup {
+                        divergentInstance {
+                            divergent {
+                                bareSignature(
+                                    mapOf("Fancy" to emptySet()),
+                                    "",
+                                    "",
+                                    emptySet(),
+                                    "function",
+                                    "String",
+                                    "abc" to ParamAttributes(mapOf("Fancy" to emptySet()), emptySet(), "String")
+                                )
+                            }
+                        }
+                    }
+
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `function with undocumented annotation`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            |@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION,
+            |    AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.EXPRESSION, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FIELD
+            |)
+            |@Retention(AnnotationRetention.SOURCE)
+            |annotation class Fancy
+            |
+            |@Fancy
+            |fun function(@Fancy abc: String): String {
+            |    return "Hello, " + abc
+            |}
+        """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" }
+                    .children.single { it.name == "function" } as ContentPage
+                page.content.assertNode {
+                    group {
+                        header(1) { +"function" }
+                    }
+                    divergentGroup {
+                        divergentInstance {
+                            divergent {
+                                bareSignature(
+                                    emptyMap(),
+                                    "",
+                                    "",
+                                    emptySet(),
+                                    "function",
+                                    "String",
+                                    "abc" to ParamAttributes(emptyMap(), emptySet(), "String")
+                                )
+                            }
+                        }
+                    }
+
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `property with undocumented annotation`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            |@Suppress
+            |val property: Int = 6
+        """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" } as PackagePageNode
+                page.content.assertNode {
+                    propertySignature(emptyMap(), "", "", emptySet(), "val", "property", "Int", "6")
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `property with documented annotation`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            |@MustBeDocumented
+            |annotation class Fancy
+            |
+            |@Fancy
+            |val property: Int = 6
+        """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" } as PackagePageNode
+                page.content.assertNode {
+                    propertySignature(mapOf("Fancy" to emptySet()), "", "", emptySet(), "val", "property", "Int", "6")
+                }
+            }
+        }
+    }
+
+
+    @Test
+    fun `rich documented annotation`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/source.kt
+            |package test
+            |
+            |@MustBeDocumented
+            |@Retention(AnnotationRetention.SOURCE)
+            |@Target(AnnotationTarget.PROPERTY)
+            |annotation class BugReport(
+            |    val assignedTo: String = "[none]",
+            |    val testCase: KClass<ABC> = ABC::class,
+            |    val status: Status = Status.UNCONFIRMED,
+            |    val ref: Reference = Reference(value = 1),
+            |    val reportedBy: Array<Reference>,
+            |    val showStopper: Boolean = false
+            |    val previousReport: BugReport?
+            |) {
+            |    enum class Status {
+            |        UNCONFIRMED, CONFIRMED, FIXED, NOTABUG
+            |    }
+            |    class ABC
+            |}
+            |annotation class Reference(val value: Long)
+            |annotation class ReferenceReal(val value: Double)
+            | 
+            |
+            |@BugReport(
+            |    assignedTo = "me",
+            |    testCase = BugReport.ABC::class,
+            |    status = BugReport.Status.FIXED,
+            |    ref = Reference(value = 2u),
+            |    reportedBy = [Reference(value = 2UL), Reference(value = 4L), 
+            |                  ReferenceReal(value = 4.9), ReferenceReal(value = 2f)],
+            |    showStopper = true,
+            |    previousReport = null
+            |)
+            |val ltint: Int = 5
+        """.trimIndent(), testConfiguration
+        ) {
+            documentablesCreationStage = { modules ->
+
+                fun expectedAnnotationValue(name: String, value: AnnotationParameterValue) = AnnotationValue(Annotations.Annotation(
+                    dri = DRI("test", name),
+                    params = mapOf("value" to value),
+                    scope = Annotations.AnnotationScope.DIRECT,
+                    mustBeDocumented = false
+                ))
+                val property = modules.flatMap { it.packages }.flatMap { it.properties }.first()
+                val annotation = property.extra[Annotations]?.let {
+                    it.directAnnotations.entries.firstNotNullOfOrNull { (_, annotations) -> annotations.firstOrNull() }
+                }
+                val annotationParams = annotation?.params ?: emptyMap()
+
+                assertEquals(expectedAnnotationValue("Reference", IntValue(2)), annotationParams["ref"])
+
+                val reportedByParam = ArrayValue(listOf(
+                    expectedAnnotationValue("Reference", LongValue(2)),
+                    expectedAnnotationValue("Reference", LongValue(4)),
+                    expectedAnnotationValue("ReferenceReal", DoubleValue(4.9)),
+                    expectedAnnotationValue("ReferenceReal", FloatValue(2f))
+                ))
+                assertEquals(reportedByParam, annotationParams["reportedBy"])
+                assertEquals(BooleanValue(true), annotationParams["showStopper"])
+                assertEquals(NullValue, annotationParams["previousReport"])
+            }
+
+            pagesTransformationStage = { module ->
+                val page = module.children.single { it.name == "test" } as PackagePageNode
+                page.content.assertNode {
+                    propertySignature(
+                        mapOf(
+                            "BugReport" to setOf(
+                                "assignedTo",
+                                "testCase",
+                                "status",
+                                "ref",
+                                "reportedBy",
+                                "showStopper",
+                                "previousReport"
+                            )
+                        ), "", "", emptySet(), "val", "ltint", "Int", "5"
+                    )
+                }
+            }
+        }
+    }
+
+    @Test
+    fun `JvmName for property with setter and getter`() {
+        testInline(
+            """
+                |/src/main/kotlin/test/source.kt
+                |package test
+                |@get:JvmName("xd")
+                |@set:JvmName("asd")
+                |var property: String
+                |    get() = ""
+                |    set(value) {}
+            """.trimIndent(), testConfiguration
+        ) {
+            documentablesCreationStage = { modules ->
+                fun expectedAnnotation(name: String) = Annotations.Annotation(
+                    dri = DRI("kotlin.jvm", "JvmName"),
+                    params = mapOf("name" to StringValue(name)),
+                    scope = Annotations.AnnotationScope.DIRECT,
+                    mustBeDocumented = true
+                )
+
+                val property = modules.flatMap { it.packages }.flatMap { it.properties }.first()
+                val getterAnnotation = property.getter?.extra?.get(Annotations)?.let {
+                    it.directAnnotations.entries.firstNotNullOfOrNull { (_, annotations) -> annotations.firstOrNull() }
+                }
+                val setterAnnotation = property.getter?.extra?.get(Annotations)?.let {
+                    it.directAnnotations.entries.firstNotNullOfOrNull { (_, annotations) -> annotations.firstOrNull() }
+                }
+
+                assertEquals(expectedAnnotation("xd"), getterAnnotation)
+                assertTrue(getterAnnotation?.mustBeDocumented!!)
+                assertEquals(Annotations.AnnotationScope.DIRECT, getterAnnotation.scope)
+
+                assertEquals(expectedAnnotation("asd"), setterAnnotation)
+                assertTrue(setterAnnotation?.mustBeDocumented!!)
+                assertEquals(Annotations.AnnotationScope.DIRECT, setterAnnotation.scope)
+            }
+        }
+    }
+
+    @Test
+    fun `annotated bounds in Kotlin`() {
+        testInline(
+            """
+             |/src/main/kotlin/test/source.kt
+             |@MustBeDocumented
+             |@Target(AnnotationTarget.TYPE_PARAMETER)
+             |annotation class Hello(val bar: String)
+             |fun <T: @Hello("abc") String> foo(arg: String): List<T> = TODO()
+            """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { root ->
+                val fooPage = root.dfs { it.name == "foo" } as MemberPageNode
+                fooPage.content.dfs { it is ContentText && it.text == "Hello" }.assertNotNull()
+            }
+        }
+    }
+
+    @Test
+    fun `annotated bounds in Java`() {
+        testInline(
+            """
+             |/src/main/java/demo/AnnotationTest.java
+             |package demo;
+             |import java.lang.annotation.*;
+             |import java.util.List;
+             |@Documented
+             |@Target({ElementType.TYPE_USE, ElementType.TYPE})
+             |@interface Hello {
+             |   public String bar() default "";
+             |}
+             |public class AnnotationTest {
+             |    public <T extends @Hello(bar = "baz") String> List<T> foo() {
+             |        return null;
+             |    }
+             |}
+            """.trimIndent(), testConfiguration
+        ) {
+            pagesTransformationStage = { root ->
+                val fooPage = root.dfs { it.name == "foo" } as MemberPageNode
+                fooPage.content.dfs { it is ContentText && it.text == "Hello" }.assertNotNull()
+            }
+        }
+    }
+}
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/FileLevelJvmNameTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/FileLevelJvmNameTest.kt
new file mode 100644
index 00000000..5809d7df
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/FileLevelJvmNameTest.kt
@@ -0,0 +1,115 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+package content.annotations
+
+import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.Annotations
+import org.jetbrains.dokka.model.StringValue
+import org.junit.jupiter.params.ParameterizedTest
+import org.junit.jupiter.params.provider.ValueSource
+import kotlin.test.assertEquals
+
+class FileLevelJvmNameTest : BaseAbstractTest() {
+    private val testConfiguration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/")
+                analysisPlatform = "jvm"
+                classpath += jvmStdlibPath!!
+            }
+        }
+    }
+
+    companion object {
+        private const val functionTest =
+            """
+            |/src/main/kotlin/test/source.kt
+            |@file:JvmName("CustomJvmName")
+            |package test
+            |
+            |fun function(abc: String): String {
+            |    return "Hello, " + abc
+            |}
+        """
+
+        private const val extensionFunctionTest =
+            """
+            |/src/main/kotlin/test/source.kt
+            |@file:JvmName("CustomJvmName")
+            |package test
+            |
+            |fun String.function(abc: String): String {
+            |    return "Hello, " + abc
+            |}
+        """
+
+        private const val propertyTest =
+            """
+            |/src/main/kotlin/test/source.kt
+            |@file:JvmName("CustomJvmName")
+            |package test
+            |
+            |val property: String
+            |   get() = ""
+        """
+
+        private const val extensionPropertyTest =
+            """
+            |/src/main/kotlin/test/source.kt
+            |@file:JvmName("CustomJvmName")
+            |package test
+            |
+            |val String.property: String
+            |   get() = ""
+        """
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = [functionTest, extensionFunctionTest])
+    fun `jvm name should be included in functions extra`(query: String) {
+        testInline(
+            query.trimIndent(), testConfiguration
+        ) {
+            documentablesCreationStage = { modules ->
+                val expectedAnnotation = Annotations.Annotation(
+                    dri = DRI("kotlin.jvm", "JvmName"),
+                    params = mapOf("name" to StringValue("CustomJvmName")),
+                    scope = Annotations.AnnotationScope.FILE,
+                    mustBeDocumented = true
+                )
+                val function = modules.flatMap { it.packages }.first().functions.first()
+                val annotation = function.extra[Annotations]?.fileLevelAnnotations?.entries?.first()?.value?.single()
+                assertEquals(emptyMap(), function.extra[Annotations]?.directAnnotations)
+                assertEquals(expectedAnnotation, annotation)
+                assertEquals(expectedAnnotation.scope, annotation?.scope)
+                assertEquals(expectedAnnotation.mustBeDocumented, annotation?.mustBeDocumented)
+            }
+        }
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = [propertyTest, extensionPropertyTest])
+    fun `jvm name should be included in properties extra`(query: String) {
+        testInline(
+            query.trimIndent(), testConfiguration
+        ) {
+            documentablesCreationStage = { modules ->
+                val expectedAnnotation = Annotations.Annotation(
+                    dri = DRI("kotlin.jvm", "JvmName"),
+                    params = mapOf("name" to StringValue("CustomJvmName")),
+                    scope = Annotations.AnnotationScope.FILE,
+                    mustBeDocumented = true
+                )
+                val properties = modules.flatMap { it.packages }.first().properties.first()
+                val annotation = properties.extra[Annotations]?.fileLevelAnnotations?.entries?.first()?.value?.single()
+                assertEquals(emptyMap(), properties.extra[Annotations]?.directAnnotations)
+                assertEquals(expectedAnnotation, annotation)
+                assertEquals(expectedAnnotation.scope, annotation?.scope)
+                assertEquals(expectedAnnotation.mustBeDocumented, annotation?.mustBeDocumented)
+            }
+        }
+    }
+}
diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
new file mode 100644
index 00000000..5a2ff93e
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
@@ -0,0 +1,144 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+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 utils.pWrapped
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+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
+                assertNotNull(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/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt
new file mode 100644
index 00000000..7612aff8
--- /dev/null
+++ b/dokka-subprojects/plugin-base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt
@@ -0,0 +1,401 @@
+/*
+ * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
+ */
+
+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 utils.ParamAttributes
+import utils.bareSignature
+import utils.pWrapped
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
+
+
+class KotlinDeprecatedTest : BaseAbstractTest() {
+
+    private val testConfiguration = dokkaConfiguration {
+        sourceSets {
+            sourceSet {
+                sourceRoots = listOf("src/")
+                classpath = listOfNotNull(jvmStdlibPath)
+                analysisPlatform = "jvm"
+            }
+        }
+    }
+
+    @Test
+    @Suppress("UNCHECKED_CAST")
+    fun `should assert util functions for deprecation`() {
+        testInline(
+            """
+            |/src/main/kotlin/kotlin/KotlinFile.kt
+            |package deprecated
+            |
+            |@Deprecated(
+            |    message = "Fancy message"
+            |)
+            |fun simpleFunction() {} 
+            """.trimIndent(),
+            testConfiguration
+        ) {
+            documentablesTransformationStage = { module ->
+                val deprecatedFunction = module.children
+                    .single { it.name == "deprecated" }.children
+                    .single { it.name == "simpleFunction" }
+
+                val isDeprecated = (deprecatedFunction as WithExtraProperties<out Documentable>).isDeprecated()
+                assertTrue(isDeprecated)
+
+                val deprecatedAnnotation = (deprecatedFunction as WithExtraProperties<out Documentable>).deprecatedAnnotation
+                assertNotNull(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 deprecated
+            |
+            |/**
+            | * 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 == "deprecated" }.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 deprecated
+            |
+            |/**
+            | * 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 == "deprecated" }.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 deprecated
+            |
+            |/**
+            | * Average function description
+            | */
+            |@DeprecatedSinceKotlin(
+            |    warningSince = "1.4",
+            |    errorSince = "1.5",
+            |    hiddenSince = "1.6"
+            |)
+            |@Deprecated(
+            |    message = "Deprecation reason bla bla"
+            |)
+            |fun oldLe