From 8e5c63d035ef44a269b8c43430f43f5c8eebfb63 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Fri, 10 Nov 2023 11:46:54 +0100 Subject: 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 --- .../src/test/kotlin/model/ClassesTest.kt | 594 +++++++++++++++++++++ .../src/test/kotlin/model/CommentTest.kt | 338 ++++++++++++ .../src/test/kotlin/model/ExtensionsTest.kt | 159 ++++++ .../src/test/kotlin/model/FunctionsTest.kt | 403 ++++++++++++++ .../src/test/kotlin/model/InheritorsTest.kt | 428 +++++++++++++++ .../plugin-base/src/test/kotlin/model/JavaTest.kt | 491 +++++++++++++++++ .../kotlin/model/MultiLanguageInheritanceTest.kt | 365 +++++++++++++ .../src/test/kotlin/model/ObjectTest.kt | 43 ++ .../src/test/kotlin/model/PackagesTest.kt | 123 +++++ .../src/test/kotlin/model/PropertyTest.kt | 277 ++++++++++ .../JavaAnnotationsForParametersTest.kt | 181 +++++++ .../model/annotations/JavaAnnotationsTest.kt | 195 +++++++ .../KotlinAnnotationsForParametersTest.kt | 105 ++++ 13 files changed, 3702 insertions(+) create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/ClassesTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/CommentTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/ExtensionsTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/FunctionsTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/InheritorsTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/JavaTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/MultiLanguageInheritanceTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/ObjectTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/PackagesTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/PropertyTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/annotations/JavaAnnotationsForParametersTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/annotations/JavaAnnotationsTest.kt create mode 100644 dokka-subprojects/plugin-base/src/test/kotlin/model/annotations/KotlinAnnotationsForParametersTest.kt (limited to 'dokka-subprojects/plugin-base/src/test/kotlin/model') diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/model/ClassesTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/model/ClassesTest.kt new file mode 100644 index 00000000..c18dfafb --- /dev/null +++ b/dokka-subprojects/plugin-base/src/test/kotlin/model/ClassesTest.kt @@ -0,0 +1,594 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package model + +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.links.TypeConstructor +import org.jetbrains.dokka.links.sureClassNames +import org.jetbrains.dokka.model.* +import org.jetbrains.dokka.model.KotlinModifier.* +import kotlin.test.assertNull +import kotlin.test.Test +import utils.* + + +class ClassesTest : AbstractModelTest("/src/main/kotlin/classes/Test.kt", "classes") { + + @Test + fun emptyClass() { + inlineModelTest( + """ + |class Klass {}""" + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + children counts 4 + } + } + } + + @Test + fun classWithConstructor() { + inlineModelTest( + """ + |class Klass(name: String) + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + children counts 4 + + with(constructors.firstOrNull().assertNotNull("Constructor")) { + visibility.values allEquals KotlinVisibility.Public + parameters counts 1 + with(parameters.firstOrNull().assertNotNull("Constructor parameter")) { + name equals "name" + type.name equals "String" + } + } + + } + } + } + + @Test + fun classWithFunction() { + inlineModelTest( + """ + |class Klass { + | fun fn() {} + |} + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + children counts 5 + + with((this / "fn").cast()) { + type.name equals "Unit" + parameters counts 0 + visibility.values allEquals KotlinVisibility.Public + } + } + } + } + + @Test + fun classWithProperty() { + inlineModelTest( + """ + |class Klass { + | val name: String = "" + |} + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + children counts 5 + + with((this / "name").cast()) { + name equals "name" + // TODO property name + } + } + } + } + + @Test + fun classWithCompanionObject() { + inlineModelTest( + """ + |class Klass() { + | companion object { + | val x = 1 + | fun foo() {} + | } + |} + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + children counts 5 + + with((this / "Companion").cast()) { + name equals "Companion" + children counts 5 + + with((this / "x").cast()) { + name equals "x" + } + + with((this / "foo").cast()) { + name equals "foo" + parameters counts 0 + type.name equals "Unit" + } + } + + with((this.companion).cast()) { + name equals "Companion" + children counts 5 + + with((this / "x").cast()) { + name equals "x" + } + + with((this / "foo").cast()) { + name equals "foo" + parameters counts 0 + type.name equals "Unit" + } + } + } + } + } + + @Test + fun dataClass() { + inlineModelTest( + """ + |data class Klass() {} + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + visibility.values allEquals KotlinVisibility.Public + with(extra[AdditionalModifiers]!!.content.entries.single().value.assertNotNull("Extras")) { + this counts 1 + first() equals ExtraModifiers.KotlinOnlyModifiers.Data + } + } + } + } + + @Test + fun sealedClass() { + inlineModelTest( + """ + |sealed class Klass() {} + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + modifier.values.forEach { it equals Sealed } + } + } + } + + @Test + fun annotatedClassWithAnnotationParameters() { + inlineModelTest( + """ + |@Deprecated("should no longer be used") class Foo() {} + """ + ) { + with((this / "classes" / "Foo").cast()) { + with(extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 1 + with(first()) { + dri.classNames equals "Deprecated" + params.entries counts 1 + (params["message"].assertNotNull("message") as StringValue).value equals "should no longer be used" + } + } + } + } + } + + @Test + fun notOpenClass() { + inlineModelTest( + """ + |open class C() { + | open fun f() {} + |} + | + |class D() : C() { + | override fun f() {} + |} + """ + ) { + val C = (this / "classes" / "C").cast() + val D = (this / "classes" / "D").cast() + + with(C) { + modifier.values.forEach { it equals Open } + with((this / "f").cast()) { + modifier.values.forEach { it equals Open } + } + } + with(D) { + modifier.values.forEach { it equals Final } + with((this / "f").cast()) { + modifier.values.forEach { it equals Open } + } + D.supertypes.flatMap { it.component2() }.firstOrNull()?.typeConstructor?.dri equals C.dri + } + } + } + + @Test + fun indirectOverride() { + inlineModelTest( + """ + |abstract class C() { + | abstract fun foo() + |} + | + |abstract class D(): C() + | + |class E(): D() { + | override fun foo() {} + |} + """ + ) { + val C = (this / "classes" / "C").cast() + val D = (this / "classes" / "D").cast() + val E = (this / "classes" / "E").cast() + + with(C) { + modifier.values.forEach { it equals Abstract } + ((this / "foo").cast()).modifier.values.forEach { it equals Abstract } + } + + with(D) { + modifier.values.forEach { it equals Abstract } + } + + with(E) { + modifier.values.forEach { it equals Final } + + } + D.supers.single().typeConstructor.dri equals C.dri + E.supers.single().typeConstructor.dri equals D.dri + } + } + + @Test + fun innerClass() { + inlineModelTest( + """ + |class C { + | inner class D {} + |} + """ + ) { + with((this / "classes" / "C").cast()) { + + with((this / "D").cast()) { + with(extra[AdditionalModifiers]!!.content.entries.single().value.assertNotNull("AdditionalModifiers")) { + this counts 1 + first() equals ExtraModifiers.KotlinOnlyModifiers.Inner + } + } + } + } + } + + @Test + fun companionObjectExtension() { + inlineModelTest( + """ + |class Klass { + | companion object Default {} + |} + | + |/** + | * The def + | */ + |val Klass.Default.x: Int get() = 1 + """ + ) { + with((this / "classes").cast()) { + properties.single().name equals "x" + (properties.single().receiver?.dri?.callable?.receiver as? TypeConstructor)?.fullyQualifiedName equals "classes.Klass.Default" + } + } + } + + @Test + fun secondaryConstructor() { + inlineModelTest( + """ + |class C() { + | /** This is a secondary constructor. */ + | constructor(s: String): this() {} + |} + """ + ) { + with((this / "classes" / "C").cast()) { + name equals "C" + constructors counts 2 + + constructors.map { it.name } allEquals "C" + + with(constructors.find { it.parameters.isEmpty() } notNull "C()") { + parameters counts 0 + } + + with(constructors.find { it.parameters.isNotEmpty() } notNull "C(String)") { + parameters counts 1 + with(parameters.firstOrNull() notNull "Constructor parameter") { + name equals "s" + type.name equals "String" + } + } + } + } + } + + @Test + fun sinceKotlin() { + inlineModelTest( + """ + |/** + | * Useful + | */ + |@SinceKotlin("1.1") + |class C + """ + ) { + with((this / "classes" / "C").cast()) { + with(extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 1 + with(first()) { + dri.classNames equals "SinceKotlin" + params.entries counts 1 + (params["version"].assertNotNull("version") as StringValue).value equals "1.1" + } + } + } + } + } + + @Test + fun privateCompanionObject() { + inlineModelTest( + """ + |class Klass { + | private companion object { + | fun fn() {} + | val a = 0 + | } + |} + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + assertNull(companion, "Companion should not be visible by default") + } + } + } + + @Test + fun companionObject() { + inlineModelTest( + """ + |class Klass { + | companion object { + | fun fn() {} + | val a = 0 + | } + |} + """ + ) { + with((this / "classes" / "Klass").cast()) { + name equals "Klass" + with((this / "Companion").cast()) { + name equals "Companion" + visibility.values allEquals KotlinVisibility.Public + + with((this / "fn").cast()) { + name equals "fn" + parameters counts 0 + receiver equals null + } + } + } + } + } + + @Test + fun annotatedClass() { + inlineModelTest( + """@Suppress("abc") class Foo() {}""" + ) { + with((this / "classes" / "Foo").cast()) { + with( + extra[Annotations]?.directAnnotations?.values?.firstOrNull()?.firstOrNull() + .assertNotNull("annotations") + ) { + dri.toString() equals "kotlin/Suppress///PointingToDeclaration/" + (params["names"].assertNotNull("param") as ArrayValue).value equals listOf(StringValue("abc")) + } + } + } + } + + @OnlyDescriptors("Bug in descriptors, DRI of entry should have [EnumEntryDRIExtra]") + @Test + fun javaAnnotationClass() { + inlineModelTest( + """ + |import java.lang.annotation.Retention + |import java.lang.annotation.RetentionPolicy + | + |@Retention(RetentionPolicy.SOURCE) + |public annotation class throws() + """ + ) { + with((this / "classes" / "throws").cast()) { + with(extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 1 + with(first()) { + dri.classNames equals "Retention" + params["value"].assertNotNull("value") equals EnumValue( + "RetentionPolicy.SOURCE", + DRI("java.lang.annotation", "RetentionPolicy.SOURCE") + ) + } + } + } + } + } + + @Test + fun genericAnnotationClass() { + inlineModelTest( + """annotation class Foo() {}""" + ) { + with((this / "classes" / "Foo").cast()) { + generics.map { it.name to it.bounds.first().name } equals listOf( + "A" to "Any", + "B" to "Any", + "C" to "Any", + "D" to "Number" + ) + } + } + } + + @Test + fun nestedGenericClasses() { + inlineModelTest( + """ + |class Outer { + | inner class Inner { } + |} + """.trimMargin() + ) { + with((this / "classes" / "Outer").cast()) { + val inner = classlikes.single().cast() + inner.generics.map { it.name to it.bounds.first().name } equals listOf("INNER" to "Any", "T" to "OUTER") + } + } + } + + @Test + fun allImplementedInterfaces() { + inlineModelTest( + """ + | interface Highest { } + | open class HighestImpl: Highest { } + | interface Lower { } + | interface LowerImplInterface: Lower { } + | class Tested : HighestImpl(), LowerImplInterface { } + """.trimIndent() + ) { + with((this / "classes" / "Tested").cast()) { + extra[ImplementedInterfaces]?.interfaces?.entries?.single()?.value?.map { it.dri.sureClassNames } + ?.sorted() equals listOf("Highest", "Lower", "LowerImplInterface").sorted() + } + } + } + + @Test + fun multipleClassInheritance() { + inlineModelTest( + """ + | open class A { } + | open class B: A() { } + | class Tested : B() { } + """.trimIndent() + ) { + with((this / "classes" / "Tested").cast()) { + supertypes.entries.single().value.map { it.typeConstructor.dri.sureClassNames }.single() equals "B" + } + } + } + + @Test + fun multipleClassInheritanceWithInterface() { + inlineModelTest( + """ + | open class A { } + | open class B: A() { } + | interface X { } + | interface Y : X { } + | class Tested : B(), Y { } + """.trimIndent() + ) { + with((this / "classes" / "Tested").cast()) { + supertypes.entries.single().value.map { it.typeConstructor.dri.sureClassNames to it.kind } + .sortedBy { it.first } equals listOf( + "B" to KotlinClassKindTypes.CLASS, + "Y" to KotlinClassKindTypes.INTERFACE + ) + } + } + } + + @Test + fun doublyTypealiasedException() { + inlineModelTest( + """ + | typealias B = RuntimeException + | typealias A = B + """.trimMargin() + ) { + with((this / "classes" / "A").cast()) { + extra[ExceptionInSupertypes].assertNotNull("Typealias A should have ExceptionInSupertypes in its extra field") + } + with((this / "classes" / "B").cast()) { + extra[ExceptionInSupertypes].assertNotNull("Typealias B should have ExceptionInSupertypes in its extra field") + } + } + } + + @Test + fun `inline classes`() { + inlineModelTest( + """ + | inline class X(val example: String) + | + | @JvmInline + | value class InlineTest(val x: String) + """.trimMargin() + ) { + with((this / "classes" / "X").cast()) { + name equals "X" + properties.first().name equals "example" + extra[AdditionalModifiers]?.content?.values?.firstOrNull() + ?.firstOrNull() equals ExtraModifiers.KotlinOnlyModifiers.Inline + } + } + } + + @Test + fun `value classes`() { + inlineModelTest( + """ + | @JvmInline + | value class InlineTest(val example: String) + """.trimMargin() + ) { + val classlike = packages.flatMap { it.classlikes }.first() as DClass + classlike.name equals "InlineTest" + classlike.properties.first().name equals "example" + classlike.extra[AdditionalModifiers]?.content?.values?.firstOrNull() + ?.firstOrNull() equals ExtraModifiers.KotlinOnlyModifiers.Value + } + } +} diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/model/CommentTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/model/CommentTest.kt new file mode 100644 index 00000000..6b00f2f0 --- /dev/null +++ b/dokka-subprojects/plugin-base/src/test/kotlin/model/CommentTest.kt @@ -0,0 +1,338 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package model + +import org.jetbrains.dokka.model.DClass +import org.jetbrains.dokka.model.DProperty +import org.jetbrains.dokka.model.doc.* +import utils.AbstractModelTest +import utils.assertNotNull +import utils.comments +import utils.docs +import kotlin.test.Test + +class CommentTest : AbstractModelTest("/src/main/kotlin/comment/Test.kt", "comment") { + + @Test + fun codeBlockComment() { + inlineModelTest( + """ + |/** + | * ```brainfuck + | * ++++++++++[>+++++++>++++++++++>+++>+<<<<-]>++.>+.+++++++..+++.>++.<<+++++++++++++++.>.+++.------.--------.>+.>. + | * ``` + | */ + |val prop1 = "" + | + | + |/** + | * ``` + | * a + b - c + | * ``` + | */ + |val prop2 = "" + """ + ) { + with((this / "comment" / "prop1").cast()) { + name equals "prop1" + with(this.docs().firstOrNull()?.children?.firstOrNull()?.assertNotNull("Code")) { + (this?.children?.firstOrNull() as? Text) + ?.body equals "++++++++++[>+++++++>++++++++++>+++>+<<<<-]>++.>+.+++++++..+++.>++.<<+++++++++++++++.>.+++.------.--------.>+.>." + + this?.params?.get("lang") equals "brainfuck" + } + } + with((this / "comment" / "prop2").cast()) { + name equals "prop2" + with(this.docs().firstOrNull()?.children?.firstOrNull()?.assertNotNull("Code")) { + (this?.children?.firstOrNull() as? Text) + ?.body equals "a + b - c" + + this?.params?.get("lang") equals null + } + } + } + } + + @Test + fun codeBlockWithIndentationComment() { + inlineModelTest( + """ + |/** + | * 1. + | * ``` + | * line 1 + | * line 2 + | * ``` + | */ + |val prop1 = "" + """ + ) { + with((this / "comment" / "prop1").cast()) { + name equals "prop1" + with(this.docs().firstOrNull()?.children?.firstOrNull()?.assertNotNull("Code")) { + val codeBlockChildren = ((this?.children?.firstOrNull() as? Li)?.children?.firstOrNull() as? CodeBlock)?.children + (codeBlockChildren?.get(0) as? Text)?.body equals " line 1" + (codeBlockChildren?.get(1) as? Br) notNull "Br" + (codeBlockChildren?.get(2) as? Text)?.body equals " line 2" + } + } + } + } + + @Test + fun emptyDoc() { + inlineModelTest( + """ + val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + name equals "property" + comments() equals "" + } + } + } + + @Test + fun emptyDocButComment() { + inlineModelTest( + """ + |/* comment */ + |val property = "test" + |fun tst() = property + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "" + } + } + } + + @Test + fun multilineDoc() { + inlineModelTest( + """ + |/** + | * doc1 + | * + | * doc2 + | * doc3 + | */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "doc1\ndoc2 doc3\n" + } + } + } + + @Test + fun multilineDocWithComment() { + inlineModelTest( + """ + |/** + | * doc1 + | * + | * doc2 + | * doc3 + | */ + |// comment + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "doc1\ndoc2 doc3\n" + } + } + } + + @Test + fun oneLineDoc() { + inlineModelTest( + """ + |/** doc */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "doc\n" + } + } + } + + @Test + fun oneLineDocWithComment() { + inlineModelTest( + """ + |/** doc */ + |// comment + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "doc\n" + } + } + } + + @Test + fun oneLineDocWithEmptyLine() { + inlineModelTest( + """ + |/** doc */ + | + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "doc\n" + } + } + } + + @Test + fun emptySection() { + inlineModelTest( + """ + |/** + | * Summary + | * @one + | */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "Summary\n\none: []" + with(docs().find { it is CustomTagWrapper && it.name == "one" }.assertNotNull("'one' entry")) { + root.children counts 0 + root.params.keys counts 0 + } + } + } + } + + @Test + fun quotes() { + inlineModelTest( + """ + |/** it's "useful" */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals """it's "useful" +""" + } + } + } + + @Test + fun section1() { + inlineModelTest( + """ + |/** + | * Summary + | * @one section one + | */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "Summary\n\none: [section one\n]" + } + } + } + + + @Test + fun section2() { + inlineModelTest( + """ + |/** + | * Summary + | * @one section one + | * @two section two + | */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "Summary\n\none: [section one\n]\ntwo: [section two\n]" + } + } + } + + @Test + fun multilineSection() { + inlineModelTest( + """ + |/** + | * Summary + | * @one + | * line one + | * line two + | */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "Summary\n\none: [line one line two\n]" + } + } + } + + @Test + fun `should be space between Markdown nodes`() { + inlineModelTest( + """ + |/** + | * Rotates paths by `amount` **radians** around (`x`, `y`). + | */ + |val property = "test" + """ + ) { + with((this / "comment" / "property").cast()) { + comments() equals "Rotates paths by amount radians around (x, y).\n" + } + } + } + + @Test + fun `should remove spaces inside indented code block`() { + inlineModelTest( + """ + |/** + | * Welcome: + | * + | * ```kotlin + | * fun main() { + | * println("Hello World!") + | * } + | * ``` + | * + | * fun thisIsACodeBlock() { + | * val butWhy = "per markdown spec, because four-spaces prefix" + | * } + | */ + |class Foo + """ + ) { + with((this / "comment" / "Foo").cast()) { + docs()[0].children[2] equals CodeBlock( + listOf( + Text( + "fun thisIsACodeBlock() {\n" + + " val butWhy = \"per markdown spec, because four-spaces prefix\"\n" + + "}" + ) + ) + ) + } + } + } + +} diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/model/ExtensionsTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/model/ExtensionsTest.kt new file mode 100644 index 00000000..a428dd1d --- /dev/null +++ b/dokka-subprojects/plugin-base/src/test/kotlin/model/ExtensionsTest.kt @@ -0,0 +1,159 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package model + +import org.jetbrains.dokka.base.transformers.documentables.CallableExtensions +import org.jetbrains.dokka.model.DClass +import org.jetbrains.dokka.model.DFunction +import org.jetbrains.dokka.model.DInterface +import org.jetbrains.dokka.model.Documentable +import org.jetbrains.dokka.model.properties.WithExtraProperties +import utils.AbstractModelTest +import kotlin.test.Test + +class ExtensionsTest : AbstractModelTest("/src/main/kotlin/classes/Test.kt", "classes") { + private fun , R : Documentable> T.checkExtension(name: String = "extension") = + with(extra[CallableExtensions]?.extensions) { + this notNull "extensions" + this counts 1 + (this?.single() as? DFunction)?.name equals name + } + + @Test + fun `should be extension for subclasses`() { + inlineModelTest( + """ + |open class A + |open class B: A() + |open class C: B() + |open class D: C() + |fun B.extension() = "" + """ + ) { + with((this / "classes" / "B").cast()) { + checkExtension() + } + with((this / "classes" / "C").cast()) { + checkExtension() + } + with((this / "classes" / "D").cast()) { + checkExtension() + } + with((this / "classes" / "A").cast()) { + extra[CallableExtensions] equals null + } + } + } + + @Test + fun `should be extension for interfaces`() { + inlineModelTest( + """ + |interface I + |interface I2 : I + |open class A: I2 + |fun I.extension() = "" + """ + ) { + + with((this / "classes" / "A").cast()) { + checkExtension() + } + with((this / "classes" / "I2").cast()) { + checkExtension() + } + with((this / "classes" / "I").cast()) { + checkExtension() + } + } + } + + @Test + fun `should be extension for external classes`() { + inlineModelTest( + """ + |abstract class A: AbstractList() + |fun AbstractCollection.extension() {} + | + |class B:Exception() + |fun Throwable.extension() = "" + """ + ) { + with((this / "classes" / "A").cast()) { + checkExtension() + } + with((this / "classes" / "B").cast()) { + checkExtension() + } + } + } + + @Test + fun `should be extension for typealias`() { + inlineModelTest( + """ + |open class A + |open class B: A() + |open class C: B() + |open class D: C() + |typealias B2 = B + |fun B2.extension() = "" + """ + ) { + with((this / "classes" / "B").cast()) { + checkExtension() + } + with((this / "classes" / "C").cast()) { + checkExtension() + } + with((this / "classes" / "D").cast()) { + checkExtension() + } + with((this / "classes" / "A").cast()) { + extra[CallableExtensions] equals null + } + } + } + + @Test + fun `should be extension for java classes`() { + val testConfiguration = dokkaConfiguration { + suppressObviousFunctions = false + sourceSets { + sourceSet { + sourceRoots = listOf("src/main/kotlin/") + classpath += jvmStdlibPath!! + } + } + } + testInline( + """ + |/src/main/kotlin/classes/Test.kt + | package classes + | fun A.extension() = "" + | + |/src/main/kotlin/classes/A.java + | package classes; + | public class A {} + | + | /src/main/kotlin/classes/B.java + | package classes; + | public class B extends A {} + """, + configuration = testConfiguration + ) { + documentablesTransformationStage = { + it.run { + with((this / "classes" / "B").cast()) { + checkExtension() + } + with((this / "classes" / "A").cast()) { + checkExtension() + } + } + } + } + } +} diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/model/FunctionsTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/model/FunctionsTest.kt new file mode 100644 index 00000000..a6291bb1 --- /dev/null +++ b/dokka-subprojects/plugin-base/src/test/kotlin/model/FunctionsTest.kt @@ -0,0 +1,403 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package model + +import org.jetbrains.dokka.links.DRI +import org.jetbrains.dokka.model.* +import utils.AbstractModelTest +import utils.assertNotNull +import utils.comments +import utils.OnlyDescriptors +import utils.name +import kotlin.test.Test + +class FunctionTest : AbstractModelTest("/src/main/kotlin/function/Test.kt", "function") { + + @Test + fun function() { + inlineModelTest( + """ + |/** + | * Function fn + | */ + |fun fn() {} + """ + ) { + with((this / "function" / "fn").cast()) { + name equals "fn" + type.name equals "Unit" + this.children.assertCount(0, "Function children: ") + } + } + } + + @Test + fun overloads() { + inlineModelTest( + """ + |/** + | * Function fn + | */ + |fun fn() {} + | /** + | * Function fn(Int) + | */ + |fun fn(i: Int) {} + """ + ) { + with((this / "function").cast()) { + val fn1 = functions.find { + it.name == "fn" && it.parameters.isEmpty() + }.assertNotNull("fn()") + val fn2 = functions.find { + it.name == "fn" && it.parameters.isNotEmpty() + }.assertNotNull("fn(Int)") + + with(fn1) { + name equals "fn" + parameters.assertCount(0) + } + + with(fn2) { + name equals "fn" + parameters.assertCount(1) + parameters.first().type.name equals "Int" + } + } + } + } + + @Test + fun functionWithReceiver() { + inlineModelTest( + """ + |/** + | * Function with receiver + | */ + |fun String.fn() {} + | + |/** + | * Function with receiver + | */ + |fun String.fn(x: Int) {} + """ + ) { + with((this / "function").cast()) { + val fn1 = functions.find { + it.name == "fn" && it.parameters.isEmpty() + }.assertNotNull("fn()") + val fn2 = functions.find { + it.name == "fn" && it.parameters.count() == 1 + }.assertNotNull("fn(Int)") + + with(fn1) { + name equals "fn" + parameters counts 0 + receiver.assertNotNull("fn() receiver") + } + + with(fn2) { + name equals "fn" + parameters counts 1 + receiver.assertNotNull("fn(Int) receiver") + parameters.first().type.name equals "Int" + } + } + } + } + + @Test + fun functionWithParams() { + inlineModelTest( + """ + |/** + | * Multiline + | * + | * Function + | * Documentation + | */ + |fun function(/** parameter */ x: Int) { + |} + """ + ) { + with((this / "function" / "function").cast()) { + comments() equals "Multiline\nFunction Documentation\n" + + name equals "function" + parameters counts 1 + parameters.firstOrNull().assertNotNull("Parameter: ").also { + it.name equals "x" + it.type.name equals "Int" + it.comments() equals "parameter\n" + } + + type.assertNotNull("Return type: ").name equals "Unit" + } + } + } + + @Test + fun functionWithNotDocumentedAnnotation() { + inlineModelTest( + """ + |@Suppress("FOO") fun f() {} + """ + ) { + with((this / "function" / "f").cast()) { + with(extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 1 + with(first()) { + dri.classNames equals "Suppress" + params.entries counts 1 + (params["names"].assertNotNull("param") as ArrayValue).value equals listOf(StringValue("FOO")) + } + } + } + } + } + + @Test + fun inlineFunction() { + inlineModelTest( + """ + |inline fun f(a: () -> String) {} + """ + ) { + with((this / "function" / "f").cast()) { + extra[AdditionalModifiers]!!.content.entries.single().value counts 1 + extra[AdditionalModifiers]!!.content.entries.single().value exists ExtraModifiers.KotlinOnlyModifiers.Inline + } + } + } + + @Test + fun suspendFunction() { + inlineModelTest( + """ + |suspend fun f() {} + """ + ) { + with((this / "function" / "f").cast()) { + extra[AdditionalModifiers]!!.content.entries.single().value counts 1 + extra[AdditionalModifiers]!!.content.entries.single().value exists ExtraModifiers.KotlinOnlyModifiers.Suspend + } + } + } + + @Test + fun suspendInlineFunctionOrder() { + inlineModelTest( + """ + |suspend inline fun f(a: () -> String) {} + """ + ) { + with((this / "function" / "f").cast()) { + extra[AdditionalModifiers]!!.content.entries.single().value counts 2 + extra[AdditionalModifiers]!!.content.entries.single().value exists ExtraModifiers.KotlinOnlyModifiers.Suspend + extra[AdditionalModifiers]!!.content.entries.single().value exists ExtraModifiers.KotlinOnlyModifiers.Inline + } + } + } + + @Test + fun inlineSuspendFunctionOrderChanged() { + inlineModelTest( + """ + |inline suspend fun f(a: () -> String) {} + """ + ) { + with((this / "function" / "f").cast()) { + with(extra[AdditionalModifiers]!!.content.entries.single().value.assertNotNull("AdditionalModifiers")) { + this counts 2 + this exists ExtraModifiers.KotlinOnlyModifiers.Suspend + this exists ExtraModifiers.KotlinOnlyModifiers.Inline + } + } + } + } + + @OnlyDescriptors("Bug in descriptors, DRI of entry should have [EnumEntryDRIExtra]") + @Test + fun functionWithAnnotatedParam() { + inlineModelTest( + """ + |@Target(AnnotationTarget.VALUE_PARAMETER) + |@Retention(AnnotationRetention.SOURCE) + |@MustBeDocumented + |public annotation class Fancy + | + |fun function(@Fancy notInlined: () -> Unit) {} + """ + ) { + with((this / "function" / "Fancy").cast()) { + with(extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 3 + with(associate { it.dri.classNames to it }) { + with(this["Target"].assertNotNull("Target")) { + (params["allowedTargets"].assertNotNull("allowedTargets") as ArrayValue).value equals listOf( + EnumValue( + "AnnotationTarget.VALUE_PARAMETER", + DRI("kotlin.annotation", "AnnotationTarget.VALUE_PARAMETER") + ) + ) + } + with(this["Retention"].assertNotNull("Retention")) { + (params["value"].assertNotNull("value") as EnumValue) equals EnumValue( + "AnnotationRetention.SOURCE", + DRI("kotlin.annotation", "AnnotationRetention.SOURCE") + ) + } + this["MustBeDocumented"].assertNotNull("MustBeDocumented").params.entries counts 0 + } + } + + } + with((this / "function" / "function" / "notInlined").cast()) { + with(this.extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 1 + with(first()) { + dri.classNames equals "Fancy" + params.entries counts 0 + } + } + } + } + } + + @Test + fun functionWithNoinlineParam() { + inlineModelTest( + """ + |fun f(noinline notInlined: () -> Unit) {} + """ + ) { + with((this / "function" / "f" / "notInlined").cast()) { + extra[AdditionalModifiers]!!.content.entries.single().value counts 1 + extra[AdditionalModifiers]!!.content.entries.single().value exists ExtraModifiers.KotlinOnlyModifiers.NoInline + } + } + } + + @OnlyDescriptors("Bug in descriptors, DRI of entry should have [EnumEntryDRIExtra]") + @Test + fun annotatedFunctionWithAnnotationParameters() { + inlineModelTest( + """ + |@Target(AnnotationTarget.VALUE_PARAMETER) + |@Retention(AnnotationRetention.SOURCE) + |@MustBeDocumented + |public annotation class Fancy(val size: Int) + | + |@Fancy(1) fun f() {} + """ + ) { + with((this / "function" / "Fancy").cast()) { + constructors counts 1 + with(constructors.first()) { + parameters counts 1 + with(parameters.first()) { + type.name equals "Int" + name equals "size" + } + } + + with(extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 3 + with(associate { it.dri.classNames to it }) { + with(this["Target"].assertNotNull("Target")) { + (params["allowedTargets"].assertNotNull("allowedTargets") as ArrayValue).value equals listOf( + EnumValue( + "AnnotationTarget.VALUE_PARAMETER", + DRI("kotlin.annotation", "AnnotationTarget.VALUE_PARAMETER") + ) + ) + } + with(this["Retention"].assertNotNull("Retention")) { + (params["value"].assertNotNull("value") as EnumValue) equals EnumValue( + "AnnotationRetention.SOURCE", + DRI("kotlin.annotation", "AnnotationRetention.SOURCE") + ) + } + this["MustBeDocumented"].assertNotNull("MustBeDocumented").params.entries counts 0 + } + } + + } + with((this / "function" / "f").cast()) { + with(this.extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 1 + with(this.first()) { + dri.classNames equals "Fancy" + params.entries counts 1 + (params["size"] as IntValue).value equals 1 + } + } + } + } + } + + @Test + fun functionWithDefaultStringParameter() { + inlineModelTest( + """ + |/src/main/kotlin/function/Test.kt + |package function + |fun f(x: String = "") {} + """ + ) { + with((this / "function" / "f").cast()) { + parameters.forEach { p -> + p.name equals "x" + p.type.name.assertNotNull("Parameter type: ") equals "String" + p.extra[DefaultValue]?.expression?.get(sourceSets.single()) equals StringConstant("") + } + } + } + } + + @Test + fun functionWithDefaultFloatParameter() { + inlineModelTest( + """ + |/src/main/kotlin/function/Test.kt + |package function + |fun f(x: Float = 3.14f) {} + """ + ) { + with((this / "function" / "f").cast()) { + parameters.forEach { p -> + p.name equals "x" + p.type.name.assertNotNull("Parameter type: ") equals "Float" + p.extra[DefaultValue]?.expression?.get(sourceSets.single()) equals FloatConstant(3.14f) + } + } + } + } + + @Test + fun sinceKotlin() { + inlineModelTest( + """ + |/** + | * Quite useful [String] + | */ + |@SinceKotlin("1.1") + |fun f(): String = "1.1 rulezz" + """ + ) { + with((this / "function" / "f").cast()) { + with(extra[Annotations]!!.directAnnotations.entries.single().value.assertNotNull("Annotations")) { + this counts 1 + with(first()) { + dri.classNames equals "SinceKotlin" + params.entries counts 1 + (params["version"].assertNotNull("version") as StringValue).value equals "1.1" + } + } + } + } + } + +} diff --git a/dokka-subprojects/plugin-base/src/test/kotlin/model/InheritorsTest.kt b/dokka-subprojects/plugin-base/src/test/kotlin/model/InheritorsTest.kt new file mode 100644 index 00000000..459dd9ac --- /dev/null +++ b/dokka-subprojects/plugin-base/src/test/kotlin/model/InheritorsTest.kt @@ -0,0 +1,428 @@ +/* + * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license. + */ + +package model + +import org.jetbrains.dokka.Platform +import org.jetbrains.dokka.base.transformers.documentables.InheritorsInfo +import org.jetbrains.dokka.model.DClass +import org.jetbrains.dokka.model.DFunction +import org.jetbrains.dokka.model.DInterface +import org.jetbrains.dokka.model.doc.P +import org.jetbrains.dokka.model.doc.Text +import utils.AbstractModelTest +import utils.assertNotNull +import kotlin.test.Test +import kotlin.test.assertTrue + +class InheritorsTest : AbstractModelTest("/src/main/kotlin/inheritors/Test.kt", "inheritors") { + + @Test + fun simple() { + inlineModelTest( + """|interface A{} + |class B() : A {} + """.trimMargin(), + ) { + with((this / "inheritors" / "A").cast()) { + val map = extra[InheritorsInfo].assertNotNull("InheritorsInfo").value + with(map.keys.also { it counts 1 }.find { it.analysisPlatform == Platform.jvm }.assertNotNull("jvm key").let { map[it]!! } + ) { + this counts 1 + first().classNames equals "B" + } + } + } + } + + @Test + fun sealed() { + inlineModelTest( + """|sealed class A {} + |class B() : A() {} + |class C() : A() {} + |class D() + """.trimMargin(), + ) { + with((this / "inheritors" / "A").cast()) { + val map = extra[InheritorsInfo].assertNotNull("InheritorsInfo").value + with(map.keys.also { it counts 1 }.find { it.analysisPlatform == Platform.jvm }.assertNotNull("jvm key").let { map[it]!! } + ) { + this counts 2 + mapNotNull { it.classNames }.sorted() equals listOf("B", "C") + } + } + } + } + + @Test + fun multiplatform() { + val configuration = dokkaConfiguration { + sourceSets { + val commonSourceSet = sourceSet { + name = "common" + sourceRoots = listOf("common/src/") + analysisPlatform = "common" + } + sourceSet { + name = "jvm" + sourceRoots = listOf("jvm/src/") + analysisPlatform = "jvm" + dependentSourceSets = setOf(commonSourceSet.value.sourceSetID) + } + sourceSet { + name = "js" + sourceRoots = listOf("js/src/") + analysisPlatform = "js" + dependentSourceSets = setOf(commonSourceSet.value.sourceSetID) + } + } + } + + testInline( + """ + |/common/src/main/kotlin/inheritors/Test.kt + |package inheritors + |interface A{} + |/jvm/src/main/kotlin/inheritors/Test.kt + |package inheritors + |class B() : A {} + |/js/src/main/kotlin/inheritors/Test.kt + |package inheritors + |class B() : A {} + |class C() : A {} + """.trimMargin(), + configuration, + cleanupOutput = false, + ) { + documentablesTransformationStage = { m -> + with((m / "inheritors" / "A").cast()) { + val map = extra[InheritorsInfo].assertNotNull("InheritorsInfo").value + with(map.keys.also { it counts 2 }) { + with(find { it.analysisPlatform == Platform.jvm }.assertNotNull("jvm key").let { map[it]!! }) { + this counts 1 + first().classNames equals "B" + } + with(find { it.analysisPlatform == Platform.js }.assertNotNull("js key").let { map[it]!! }) { + this counts 2 + val classes = listOf("B", "C") + assertTrue(all { classes.contains(it.classNames) }, "One of subclasses missing in js" ) + } + } + + } + } + } + } + + @Test + fun `should inherit docs`() { + val expectedDoc = listOf(P(listOf(Text("some text")))) + inlineModelTest( + """|interface A { + | /** + | * some text + | */ + | val a: Int + | + | /** + | * some text + | */ + | fun b(): E + |} + |open class C + |class B() : C(), A { + | val a = 0 + | override fun b(): E {} + |} + """.trimMargin(), + platform = Platform.common.toString() + ) { + with((this / "inheritors" / "A").cast()) { + with(this / "a") { + val propDoc = this?.documentation?.values?.single()?.children?.first()?.children + propDoc equals expectedDoc + } + with(this / "b") { + val funDoc = this?.documentation?.values?.single()?.children?.first()?.children + funDoc equals expectedDoc + } + + } + + with((this / "inheritors" / "B").cast()) { + with(this / "a") { + val propDoc = this?.documentation?.values?.single()?.children?.first()?.children + propDoc equals expectedDoc + } + } + } + } + +// TODO [beresnev] fix, needs access to analysis +// class IgnoreCommonBuiltInsPlugin : DokkaPlugin() { +// private val kotlinAnalysisPlugin by lazy { plugin() } +// @Suppress("unused") +// val stdLibKotlinAnalysis by extending { +// kotlinAnalysisPlugin.kotlinAnalysis providing { ctx -> +// ProjectKotlinAnalysis( +// sourceSets = ctx.configuration.sourceSets, +// logger = ctx.logger, +// analysisConfiguration = DokkaAnalysisConfiguration(ignoreCommonBuiltIns = true) +// ) +// } override kotlinAnalysisPlugin.defaultKotlinAnalysis +// } +// +// @OptIn(DokkaPluginApiPreview::class) +// override fun pluginApiPreviewAcknowledgement(): PluginApiPreviewAcknowledgement = +// PluginApiPreviewAcknowledgement +// } +// @Test +// fun `should inherit docs for stdLib #2638`() { +// val testConfiguration = dokkaConfiguration { +// suppressObviousFunctions = false +// sourceSets { +// sourceSet { +// sourceRoots = listOf("src/") +// analysisPlatform = "common" +// languageVersion = "1.4" +// } +// } +// } +// +// inlineModelTest( +// """ +// package kotlin.collections +// +// import kotlin.internal.PlatformDependent +// +// /** +// * Classes that inherit from this interface can be represented as a sequence of elements that can +// * be iterated over. +// * @param T the type of element being iterated over. The iterator is covariant in its element type. +// */ +// public interface Iterable { +// /** +// * Returns an iterator over the elements of this object. +// */ +// public operator fun iterator(): Iterator +// } +// +// /** +// * Classes that inherit from this interface can be represented as a sequence of elements that can +// * be iterated over and that supports removing elements during iteration. +// * @param T the type of element being iterated over. The mutable iterator is invariant in its element type. +// */ +// public interface MutableIterable : Iterable { +// /** +// * Returns an iterator over the elements of this sequence that supports removing elements during iteration. +// */ +// override fun iterator(): MutableIterator +// } +// +// /** +// * A generic collection of elements. Methods in this interface support only read-only access to the collection; +// * read/write access is supported through the [MutableCollection] interface. +// * @param E the type of elements contained in the collection. The collection is covariant in its element type. +// */ +// public interface Collection : Iterable { +// // Query Operations +// /** +// * Returns the size of the collection. +// */ +// public val size: Int +// +// /** +// * Returns `true` if the collection is empty (contains no elements), `false` otherwise. +// */ +// public fun isEmpty(): Boolean +// +// /** +// * Checks if the specified element is contained in this collection. +// */ +// public operator fun contains(element: @UnsafeVariance E): Boolean +// +// override fun iterator(): Iterator +// +// // Bulk Operations +// /** +// * Checks if all elements in the specified collection are contained in this collection. +// */ +// public fun containsAll(elements: Collection<@UnsafeVariance E>): Boolean +// } +// +// /** +// * A generic collection of elements that supports adding and removing elements. +// * +// * @param E the type of elements contained in the collection. The mutable collection is invariant in its element type. +// */ +// public interface MutableCollection : Collection, MutableIterable { +// // Query Operations +// override fun iterator(): MutableIterator +// +// // Modification Operations +// /** +// * Adds the specified element to the collection. +// * +// * @return `true` if the element has been added, `false` if the collection does not support duplicates +// * and the element is already contained in the collection. +// */ +// public fun add(element: E): Boolean +// +// /** +// * Removes a single instance of the specified element from this +// * collection, if it is present. +// * +// * @return `true` if the element has been successfully removed; `false` if it was not present in the collection. +// */ +// public fun remove(element: E): Boolean +// +// // Bulk Modification Operations +// /** +// * Adds all of the elements of the specified collection to this collection. +// * +// * @return `true` if any of the specified elements was added to the collection, `false` if the collection was not modified. +// */ +// public fun addAll(elements: Collection): Boolean +// +// /** +// * Removes all of this collection's elements that are also contained in the specified collection. +// * +// * @return `true` if any of the specified elements was removed from the collection, `false` if the collection was not modified. +// */ +// public fun removeAll(elements: Collection): Boolean +// +// /** +// * Retains only the elements in this collection that are contained in the specified collection. +// * +// * @return `true` if any element was removed from the collection, `false` if the collection was not modified. +// */ +// public fun retainAll(elements: Collection): Boolean +// +// /** +// * Removes all elements from this collection. +// */ +// public fun clear(): Unit +// } +// +// /** +//