From 4f231b3666568e1f2a5a3241e87c2cbc26af6127 Mon Sep 17 00:00:00 2001 From: Marcin Aman Date: Tue, 15 Dec 2020 17:32:50 +0100 Subject: Fix wrong docs on DProperty (#1671) --- .../ContentForClassWithParamsAndPropertiesTest.kt | 268 +++++++++++++++++++++ 1 file changed, 268 insertions(+) create mode 100644 plugins/base/src/test/kotlin/content/properties/ContentForClassWithParamsAndPropertiesTest.kt (limited to 'plugins/base/src/test/kotlin/content/properties/ContentForClassWithParamsAndPropertiesTest.kt') diff --git a/plugins/base/src/test/kotlin/content/properties/ContentForClassWithParamsAndPropertiesTest.kt b/plugins/base/src/test/kotlin/content/properties/ContentForClassWithParamsAndPropertiesTest.kt new file mode 100644 index 00000000..5bd152dc --- /dev/null +++ b/plugins/base/src/test/kotlin/content/properties/ContentForClassWithParamsAndPropertiesTest.kt @@ -0,0 +1,268 @@ +package content.properties + +import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.model.DClass +import org.jetbrains.dokka.model.dfs +import org.jetbrains.dokka.model.doc.* +import org.jetbrains.dokka.pages.ClasslikePageNode +import org.jetbrains.dokka.pages.RootPageNode +import org.junit.jupiter.api.Test +import kotlin.test.assertEquals + +class ContentForClassWithParamsAndPropertiesTest : BaseAbstractTest() { + private val testConfiguration = dokkaConfiguration { + sourceSets { + sourceSet { + sourceRoots = listOf("src/") + analysisPlatform = "jvm" + } + } + } + + @Test + fun `should work for a simple property`() { + propertyTest { rootPage -> + val node = rootPage.dfs { it.name == "LoadInitialParams" } as ClasslikePageNode + val actualDocsForPlaceholdersEnabled = + (node.documentable as DClass).constructors.first().parameters.find { it.name == "placeholdersEnabled" } + ?.documentation?.entries?.first()?.value + assertEquals(DocumentationNode(listOf(docsForPlaceholdersEnabled)), actualDocsForPlaceholdersEnabled) + } + } + + @Test + fun `should work for a simple with linebreak`() { + propertyTest { rootPage -> + val node = rootPage.dfs { it.name == "LoadInitialParams" } as ClasslikePageNode + val actualDocsForRequestedLoadSize = + (node.documentable as DClass).constructors.first().parameters.find { it.name == "requestedLoadSize" } + ?.documentation?.entries?.first()?.value + assertEquals(DocumentationNode(listOf(docsForRequestedLoadSize)), actualDocsForRequestedLoadSize) + } + } + + @Test + fun `should work with multiline property inline code`() { + propertyTest { rootPage -> + val node = rootPage.dfs { it.name == "LoadInitialParams" } as ClasslikePageNode + + val actualDocsForRequestedInitialKey = + (node.documentable as DClass).constructors.first().parameters.find { it.name == "requestedInitialKey" } + ?.documentation?.entries?.first()?.value + assertEquals(DocumentationNode(listOf(docsForRequestedInitialKey)), actualDocsForRequestedInitialKey) + } + } + + @Test + fun `constructor should only the param and constructor tags`() { + propertyTest { rootPage -> + val constructorDocs = Description( + root = CustomDocTag( + children = listOf( + P( + children = listOf( + Text("Creates an empty group.") + ) + ) + ), + emptyMap(), "MARKDOWN_FILE" + ) + ) + val node = rootPage.dfs { it.name == "LoadInitialParams" } as ClasslikePageNode + + val actualDocs = + (node.documentable as DClass).constructors.first().documentation.entries.first().value + assertEquals(DocumentationNode(listOf(constructorDocs, docsForParam)), actualDocs) + } + } + + @Test + fun `class should have all tags`() { + propertyTest { rootPage -> + val ownDescription = Description( + root = CustomDocTag( + children = listOf( + P( + children = listOf( + Text("Holder object for inputs to loadInitial.") + ) + ) + ), + emptyMap(), "MARKDOWN_FILE" + ) + ) + val node = rootPage.dfs { it.name == "LoadInitialParams" } as ClasslikePageNode + + val actualDocs = + (node.documentable as DClass).documentation.entries.first().value + assertEquals( + DocumentationNode( + listOf( + ownDescription, + docsForParam, + docsForRequestedInitialKey, + docsForRequestedLoadSize, + docsForPlaceholdersEnabled, + docsForConstructor + ) + ), + actualDocs + ) + } + } + + @Test + fun `property should also work with own docs that override the param tag`() { + propertyTest { rootPage -> + val ownDescription = Description( + root = CustomDocTag( + children = listOf( + P( + children = listOf( + Text("Own docs") + ) + ) + ), + emptyMap(), "MARKDOWN_FILE" + ) + ) + val node = rootPage.dfs { it.name == "ItemKeyedDataSource" } as ClasslikePageNode + + val actualDocs = + (node.documentable as DClass).properties.first().documentation.entries.first().value + assertEquals( + DocumentationNode(listOf(ownDescription)), + actualDocs + ) + } + } + + + private fun propertyTest(block: (RootPageNode) -> Unit) { + testInline( + """ |/src/main/kotlin/test/source.kt + |package test + |/** + | * @property tested Docs from class + | */ + |abstract class ItemKeyedDataSource : DataSource(ITEM_KEYED) { + | /** + | * Own docs + | */ + | val tested = "" + | + | /** + | * Holder object for inputs to loadInitial. + | * + | * @param Key Type of data used to query Value types out of the DataSource. + | * @property requestedInitialKey Load items around this key, or at the beginning of the data set + | * if `null` is passed. + | * + | * Note that this key is generally a hint, and may be ignored if you want to always load from + | * the beginning. + | * @property requestedLoadSize Requested number of items to load. + | * + | * Note that this may be larger than available data. + | * @property placeholdersEnabled Defines whether placeholders are enabled, and whether the + | * loaded total count will be ignored. + | * + | * @constructor Creates an empty group. + | */ + | open class LoadInitialParams( + | @JvmField + | val requestedInitialKey: Key?, + | @JvmField + | val requestedLoadSize: Int, + | @JvmField + | val placeholdersEnabled: Boolean + | ) + |}""".trimIndent(), testConfiguration + ) { + pagesGenerationStage = block + } + } + + private val docsForPlaceholdersEnabled = Property( + root = CustomDocTag( + listOf( + P( + children = listOf( + Text("Defines whether placeholders are enabled, and whether the loaded total count will be ignored.") + ) + ) + ), emptyMap(), "MARKDOWN_FILE" + ), + name = "placeholdersEnabled" + ) + + private val docsForRequestedInitialKey = Property( + root = CustomDocTag( + listOf( + P( + children = listOf( + Text("Load items around this key, or at the beginning of the data set if "), + CodeInline( + listOf( + Text("null") + ) + ), + Text(" is passed.") + ), + params = emptyMap() + ), + P( + children = listOf( + Text("Note that this key is generally a hint, and may be ignored if you want to always load from the beginning.") + ) + ) + ), emptyMap(), "MARKDOWN_FILE" + ), + name = "requestedInitialKey" + ) + + private val docsForRequestedLoadSize = Property( + root = CustomDocTag( + listOf( + P( + children = listOf( + Text("Requested number of items to load.") + ) + ), + P( + children = listOf( + Text("Note that this may be larger than available data.") + ) + ) + ), emptyMap(), "MARKDOWN_FILE" + ), + name = "requestedLoadSize" + ) + + private val docsForConstructor = Constructor( + root = CustomDocTag( + children = listOf( + P( + children = listOf( + Text("Creates an empty group.") + ) + ) + ), + emptyMap(), "MARKDOWN_FILE" + ) + ) + + private val docsForParam = Param( + root = CustomDocTag( + children = listOf( + P( + children = listOf( + Text("Type of data used to query Value types out of the DataSource.") + ) + ) + ), + emptyMap(), "MARKDOWN_FILE" + ), + name = "Key" + ) +} + -- cgit