Add deprecation details block (#2622)

3 files changed, 536 insertions, 44 deletions

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/DepredatedAndSinceKotlinTest.kt b/plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt
index e0aa1d04..84f5b647 100644
--- a/plugins/base/src/test/kotlin/content/annotations/DepredatedAndSinceKotlinTest.kt
+++ b/plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt
@@ -1,15 +1,13 @@
 package content.annotations
 
-
 import matchers.content.*
-import org.jetbrains.dokka.pages.ContentPage
 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 DepredatedAndSinceKotlinTest : BaseAbstractTest() {
+class SinceKotlinTest : BaseAbstractTest() {
 
     private val testConfiguration = dokkaConfiguration {
         sourceSets {
@@ -21,46 +19,6 @@ class DepredatedAndSinceKotlinTest : BaseAbstractTest() {
     }
 
     @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(
             """