aboutsummaryrefslogtreecommitdiff
path: root/plugins/base/src/test/kotlin/content/annotations
diff options
context:
space:
mode:
authorIgnat Beresnev <ignat.beresnev@jetbrains.com>2023-11-10 11:46:54 +0100
committerGitHub <noreply@github.com>2023-11-10 11:46:54 +0100
commit8e5c63d035ef44a269b8c43430f43f5c8eebfb63 (patch)
tree1b915207b2b9f61951ddbf0ff2e687efd053d555 /plugins/base/src/test/kotlin/content/annotations
parenta44efd4ba0c2e4ab921ff75e0f53fc9335aa79db (diff)
downloaddokka-8e5c63d035ef44a269b8c43430f43f5c8eebfb63.tar.gz
dokka-8e5c63d035ef44a269b8c43430f43f5c8eebfb63.tar.bz2
dokka-8e5c63d035ef44a269b8c43430f43f5c8eebfb63.zip
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>
Diffstat (limited to 'plugins/base/src/test/kotlin/content/annotations')
-rw-r--r--plugins/base/src/test/kotlin/content/annotations/ContentForAnnotationsTest.kt351
-rw-r--r--plugins/base/src/test/kotlin/content/annotations/FileLevelJvmNameTest.kt115
-rw-r--r--plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt144
-rw-r--r--plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt401
-rw-r--r--plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt350
5 files changed, 0 insertions, 1361 deletions
diff --git a/plugins/base/src/test/kotlin/content/annotations/ContentForAnnotationsTest.kt b/plugins/base/src/test/kotlin/content/annotations/ContentForAnnotationsTest.kt
deleted file mode 100644
index 7293b53c..00000000
--- a/plugins/base/src/test/kotlin/content/annotations/ContentForAnnotationsTest.kt
+++ /dev/null
@@ -1,351 +0,0 @@
-/*
- * 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/plugins/base/src/test/kotlin/content/annotations/FileLevelJvmNameTest.kt b/plugins/base/src/test/kotlin/content/annotations/FileLevelJvmNameTest.kt
deleted file mode 100644
index 5809d7df..00000000
--- a/plugins/base/src/test/kotlin/content/annotations/FileLevelJvmNameTest.kt
+++ /dev/null
@@ -1,115 +0,0 @@
-/*
- * 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/plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt b/plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
deleted file mode 100644
index 5a2ff93e..00000000
--- a/plugins/base/src/test/kotlin/content/annotations/JavaDeprecatedTest.kt
+++ /dev/null
@@ -1,144 +0,0 @@
-/*
- * 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/plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt b/plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt
deleted file mode 100644
index 7612aff8..00000000
--- a/plugins/base/src/test/kotlin/content/annotations/KotlinDeprecatedTest.kt
+++ /dev/null
@@ -1,401 +0,0 @@
-/*
- * 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 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"
- }
- 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 deprecated
- |
- |/**
- | * 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 == "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 {
- +("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
deleted file mode 100644
index 6ee95bbd..00000000
--- a/plugins/base/src/test/kotlin/content/annotations/SinceKotlinTest.kt
+++ /dev/null
@@ -1,350 +0,0 @@
-/*
- * 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.Platform
-import org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinTransformer
-import org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinVersion
-import org.jetbrains.dokka.model.DFunction
-import org.jetbrains.dokka.model.dfs
-import org.jetbrains.dokka.model.doc.CustomTagWrapper
-import org.jetbrains.dokka.model.doc.Text
-import org.jetbrains.dokka.pages.ContentPage
-import signatures.AbstractRenderingTest
-import utils.*
-import kotlin.test.*
-
-
-class SinceKotlinTest : AbstractRenderingTest() {
-
- val testConfiguration = dokkaConfiguration {
- sourceSets {
- sourceSet {
- sourceRoots = listOf("src/")
- classpath = listOfNotNull(jvmStdlibPath)
- analysisPlatform = "jvm"
- }
- }
- }
-
- @BeforeTest
- fun setSystemProperty() {
- System.setProperty(SinceKotlinTransformer.SHOULD_DISPLAY_SINCE_KOTLIN_SYS_PROP, "true")
- }
- @AfterTest
- fun clearSystemProperty() {
- System.clearProperty(SinceKotlinTransformer.SHOULD_DISPLAY_SINCE_KOTLIN_SYS_PROP)
- }
-
- @Test
- fun versionsComparing() {
- assertTrue(SinceKotlinVersion("1.0").compareTo(SinceKotlinVersion("1.0")) == 0)
- assertTrue(SinceKotlinVersion("1.0.0").compareTo(SinceKotlinVersion("1")) == 0)
- assertTrue(SinceKotlinVersion("1.0") >= SinceKotlinVersion("1.0"))
- assertTrue(SinceKotlinVersion("1.1") > SinceKotlinVersion("1"))
- assertTrue(SinceKotlinVersion("1.0") < SinceKotlinVersion("2.0"))
- assertTrue(SinceKotlinVersion("1.0") < SinceKotlinVersion("2.2"))
- }
-
- @Test
- fun `rendered SinceKotlin custom tag for typealias, extensions, functions, properties`() {
- val writerPlugin = TestOutputWriterPlugin()
-
- testInline(
- """
- |/src/main/kotlin/test/source.kt
- |package test
- |
- |@SinceKotlin("1.5")
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |@SinceKotlin("1.5")
- |fun String.extension(abc: String): String {
- | return "My precious " + abc
- |}
- |@SinceKotlin("1.5")
- |typealias Str = String
- |@SinceKotlin("1.5")
- |val str = "str"
- """.trimIndent(),
- testConfiguration,
- pluginOverrides = listOf(writerPlugin)
- ) {
- renderingStage = { _, _ ->
- val content = writerPlugin.renderedContent("root/test/index.html")
- assertEquals(4, content.getElementsContainingOwnText("Since Kotlin").count())
- }
- }
- }
-
- @Test
- fun `should propagate SinceKotlin`() {
- testInline(
- """
- |/src/main/kotlin/test/source.kt
- |package test
- |
- |@SinceKotlin("1.5")
- |class A {
- | fun ring(abc: String): String {
- | return "My precious " + abc
- | }
- |}
- """.trimIndent(), testConfiguration
- ) {
- documentablesTransformationStage = { module ->
- @Suppress("UNCHECKED_CAST") val funcs = module.children.single { it.name == "test" }
- .children.single { it.name == "A" }
- .children.filter { it.name == "ring" && it is DFunction } as List<DFunction>
- with(funcs) {
- val sinceKotlin = mapOf(
- Platform.jvm to SinceKotlinVersion("1.5"),
- )
-
- for(i in sinceKotlin) {
- val tag =
- find { it.sourceSets.first().analysisPlatform == i.key }?.documentation?.values?.first()
- ?.dfs { it is CustomTagWrapper && it.name == "Since Kotlin" }
- .assertNotNull("SinceKotlin[${i.key}]")
- assertEquals((tag.children.first() as Text).body, i.value.toString())
- }
- }
- }
- }
- }
-
- @Test
- fun `mpp fun without SinceKotlin annotation`() {
- val configuration = dokkaConfiguration {
- sourceSets {
- sourceSet {
- sourceRoots = listOf("src/jvm/")
- analysisPlatform = "jvm"
- }
- sourceSet {
- sourceRoots = listOf("src/native/")
- analysisPlatform = "native"
- name = "native"
- }
- sourceSet {
- sourceRoots = listOf("src/common/")
- analysisPlatform = "common"
- name = "common"
- }
- sourceSet {
- sourceRoots = listOf("src/js/")
- analysisPlatform = "js"
- name = "js"
- }
- sourceSet {
- sourceRoots = listOf("src/wasm/")
- analysisPlatform = "wasm"
- name = "wasm"
- }
- }
- }
- testInline(
- """
- |/src/jvm/kotlin/test/source.kt
- |package test
- |
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/native/kotlin/test/source.kt
- |package test
- |
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/common/kotlin/test/source.kt
- |package test
- |
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/js/kotlin/test/source.kt
- |package test
- |
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/wasm/kotlin/test/source.kt
- |package test
- |
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- """.trimIndent(), configuration
- ) {
- documentablesTransformationStage = { module ->
- @Suppress("UNCHECKED_CAST") val funcs = module.children.single { it.name == "test" }
- .children.filter { it.name == "ring" && it is DFunction } as List<DFunction>
- with(funcs) {
- val sinceKotlin = mapOf(
- Platform.common to SinceKotlinVersion("1.0"),
- Platform.jvm to SinceKotlinVersion("1.0"),
- Platform.js to SinceKotlinVersion("1.1"),
- Platform.native to SinceKotlinVersion("1.3"),
- Platform.wasm to SinceKotlinVersion("1.8"),
- )
-
- for(i in sinceKotlin) {
- val tag =
- find { it.sourceSets.first().analysisPlatform == i.key }?.documentation?.values?.first()
- ?.dfs { it is CustomTagWrapper && it.name == "Since Kotlin" }
- .assertNotNull("SinceKotlin[${i.key}]")
- assertEquals((tag.children.first() as Text).body, i.value.toString())
- }
- }
- }
- }
- }
-
- @Test
- fun `mpp fun with SinceKotlin annotation`() {
- val configuration = dokkaConfiguration {
- sourceSets {
- sourceSet {
- sourceRoots = listOf("src/jvm/")
- classpath = listOfNotNull(jvmStdlibPath)
- analysisPlatform = "jvm"
- }
- sourceSet {
- sourceRoots = listOf("src/native/")
- analysisPlatform = "native"
- name = "native"
- }
- sourceSet {
- sourceRoots = listOf("src/common/")
- classpath = listOfNotNull(commonStdlibPath)
- analysisPlatform = "common"
- name = "common"
- }
- sourceSet {
- sourceRoots = listOf("src/js/")
- classpath = listOfNotNull(jsStdlibPath)
- analysisPlatform = "js"
- name = "js"
- }
- sourceSet {
- sourceRoots = listOf("src/wasm/")
- analysisPlatform = "wasm"
- name = "wasm"
- }
- }
- }
- testInline(
- """
- |/src/jvm/kotlin/test/source.kt
- |package test
- |
- |/** dssdd */
- |@SinceKotlin("1.3")
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/native/kotlin/test/source.kt
- |package test
- |
- |/** dssdd */
- |@SinceKotlin("1.3")
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/common/kotlin/test/source.kt
- |package test
- |
- |/** dssdd */
- |@SinceKotlin("1.3")
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/js/kotlin/test/source.kt
- |package test
- |
- |/** dssdd */
- |@SinceKotlin("1.3")
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- |/src/wasm/kotlin/test/source.kt
- |package test
- |
- |/** dssdd */
- |@SinceKotlin("1.3")
- |fun ring(abc: String): String {
- | return "My precious " + abc
- |}
- """.trimIndent(), configuration
- ) {
- documentablesTransformationStage = { module ->
- @Suppress("UNCHECKED_CAST") val funcs = module.children.single { it.name == "test" }
- .children.filter { it.name == "ring" && it is DFunction } as List<DFunction>
- with(funcs) {
- val sinceKotlin = mapOf(
- Platform.common to SinceKotlinVersion("1.3"),
- Platform.jvm to SinceKotlinVersion("1.3"),
- Platform.js to SinceKotlinVersion("1.3"),
- Platform.native to SinceKotlinVersion("1.3"),
- Platform.wasm to SinceKotlinVersion("1.8"),
- )
-
- for(i in sinceKotlin) {
- val tag =
- find { it.sourceSets.first().analysisPlatform == i.key }?.documentation?.values?.first()
- ?.dfs { it is CustomTagWrapper && it.name == "Since Kotlin" }
- .assertNotNull("SinceKotlin[${i.key}]")
- assertEquals(i.value.toString(), (tag.children.first() as Text).body , "Platform ${i.key}")
- }
- }
- }
- }
- }
-
- @Test
- fun `should do not render since kotlin tag when flag is unset`() {
- clearSystemProperty()
- 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")
- )
- }
- }
- }
-
- }
- }
- }
- }
-}