From bfd41ce2a0d43419a671961c19b7d755cffdcfc8 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 23 Dec 2021 14:32:18 +0300 Subject: Introduce documentedVisibilities setting (#2270) * Introduce `documentedVisibilities` setting * Remove hardcoded doc generation for Visibility.PUBLIC, correct tests * Add maven, gradle and cli integration tests for documentedVisibilities * Fix maven plugin configuration overriding the default value * Remove test debug prints * Correct an inconsistency with default values and leave a comment of intentions * Add a test for visibility of private setter --- .../DocumentableVisibilityFilterTransformer.kt | 28 +- .../content/signatures/ContentForSignaturesTest.kt | 8 +- .../test/kotlin/filter/DeprecationFilterTest.kt | 8 +- .../test/kotlin/filter/JavaVisibilityFilterTest.kt | 195 ++++++++- .../src/test/kotlin/filter/VisibilityFilterTest.kt | 442 ++++++++++++++++++++- plugins/base/src/test/kotlin/model/JavaTest.kt | 8 +- .../ReportUndocumentedTransformerTest.kt | 6 +- ...nfigurationDocumentableFilterTransformerTest.kt | 2 + ...efaultDescriptorToDocumentableTranslatorTest.kt | 12 +- 9 files changed, 684 insertions(+), 25 deletions(-) (limited to 'plugins/base/src') diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt index bd39b040..4b9da03b 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt @@ -5,6 +5,7 @@ import org.jetbrains.dokka.model.* import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.DokkaDefaults class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMergeDocumentableTransformer { @@ -20,10 +21,29 @@ class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMe ) { fun Visibility.isAllowedInPackage(packageName: String?) = when (this) { is JavaVisibility.Public, - is KotlinVisibility.Public -> true - else -> packageName != null - && packageOptions.firstOrNull { Regex(it.matchingRegex).matches(packageName) }?.includeNonPublic - ?: globalOptions.includeNonPublic + is KotlinVisibility.Public -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PUBLIC) + is JavaVisibility.Private, + is KotlinVisibility.Private -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PRIVATE) + is JavaVisibility.Protected, + is KotlinVisibility.Protected -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PROTECTED) + is KotlinVisibility.Internal -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.INTERNAL) + is JavaVisibility.Default -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PACKAGE) + } + + private fun isAllowedInPackage(packageName: String?, visibility: DokkaConfiguration.Visibility): Boolean { + val packageOpts = packageName.takeIf { it != null }?.let { name -> + packageOptions.firstOrNull { Regex(it.matchingRegex).matches(name) } + } + + val (documentedVisibilities, includeNonPublic) = when { + packageOpts != null -> packageOpts.documentedVisibilities to packageOpts.includeNonPublic + else -> globalOptions.documentedVisibilities to globalOptions.includeNonPublic + } + + // if `documentedVisibilities` is explicitly overridden by the user (i.e. not default value by reference), + // deprecated `includeNonPublic` should not be taken into account, so that only one setting prevails + val isDocumentedVisibilitiesOverridden = documentedVisibilities !== DokkaDefaults.documentedVisibilities + return documentedVisibilities.contains(visibility) || (!isDocumentedVisibilitiesOverridden && includeNonPublic) } fun processModule(original: DModule) = diff --git a/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt b/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt index e7c35a66..c0f1ebfb 100644 --- a/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt +++ b/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt @@ -1,6 +1,7 @@ package content.signatures import matchers.content.* +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.model.doc.Text import org.jetbrains.dokka.pages.* @@ -18,7 +19,12 @@ class ContentForSignaturesTest : BaseAbstractTest() { sourceSet { sourceRoots = listOf("src/") analysisPlatform = "jvm" - includeNonPublic = true + documentedVisibilities = setOf( + DokkaConfiguration.Visibility.PUBLIC, + DokkaConfiguration.Visibility.PRIVATE, + DokkaConfiguration.Visibility.PROTECTED, + DokkaConfiguration.Visibility.INTERNAL, + ) } } } diff --git a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt index 4431d383..e6f2c5e9 100644 --- a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt @@ -1,5 +1,6 @@ package filter +import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest import org.junit.jupiter.api.Assertions @@ -109,7 +110,8 @@ class DeprecationFilterTest : BaseAbstractTest() { true, false, true, - false + false, + DokkaDefaults.documentedVisibilities ) ) } @@ -147,7 +149,9 @@ class DeprecationFilterTest : BaseAbstractTest() { false, false, false, - false) + false, + DokkaDefaults.documentedVisibilities + ) ) } } diff --git a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt index 32c00e92..e6acec92 100644 --- a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt @@ -1,17 +1,204 @@ package filter +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.DokkaConfigurationImpl +import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.model.DClass +import org.jetbrains.dokka.model.DModule +import org.junit.jupiter.api.Test import org.junit.jupiter.params.ParameterizedTest import org.junit.jupiter.params.provider.MethodSource import testApi.testRunner.dokkaConfiguration import kotlin.test.assertEquals class JavaVisibilityFilterTest : BaseAbstractTest() { + + @Test + fun `should document nothing private if no visibilities are included`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | private String privateProperty = "privateProperty"; + | + | public void publicFunction() { } + | private void privateFunction() { } + | } + """.trimIndent(), + includedVisibility = DokkaDefaults.documentedVisibilities + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(1, it.size) + assertEquals("publicProperty", it[0].name) + } + clazz.functions.also { + assertEquals(1, it.size) + assertEquals("publicFunction", it[0].name) + } + } + } + + @Test + fun `should document private within public class`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | protected String noise = "noise"; + | + | private String privateProperty = "privateProperty"; + | + | public void publicFunction() { } + | private void privateFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PRIVATE) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("privateProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFunction", it[0].name) + assertEquals("privateFunction", it[1].name) + } + } + } + + @Test + fun `should document package private within private class`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | protected String noise = "noise"; + | + | String packagePrivateProperty = "packagePrivateProperty"; + | + | public void publicFunction() { } + | void packagePrivateFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PACKAGE) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("packagePrivateProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFunction", it[0].name) + assertEquals("packagePrivateFunction", it[1].name) + } + } + } + + @Test + fun `should document protected within public class`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | String noise = "noise"; + | + | protected String protectedProperty = "protectedProperty"; + | + | public void publicFunction() { } + | protected void protectedFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PROTECTED) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("protectedProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFunction", it[0].name) + assertEquals("protectedFunction", it[1].name) + } + } + } + + @Test + fun `should include all visibilities`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | private String privateProperty = "privateProperty"; + | String packagePrivateProperty = "packagePrivateProperty"; + | protected String protectedProperty = "protectedProperty"; + | + | public void publicFunction() { } + | private void privateFunction() { } + | void packagePrivateFunction() { } + | protected void protectedFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf( + DokkaConfiguration.Visibility.PUBLIC, + DokkaConfiguration.Visibility.PRIVATE, + DokkaConfiguration.Visibility.PROTECTED, + DokkaConfiguration.Visibility.PACKAGE, + ) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(4, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("privateProperty", it[1].name) + assertEquals("packagePrivateProperty", it[2].name) + assertEquals("protectedProperty", it[3].name) + } + clazz.functions.also { + assertEquals(4, it.size) + assertEquals("publicFunction", it[0].name) + assertEquals("privateFunction", it[1].name) + assertEquals("packagePrivateFunction", it[2].name) + assertEquals("protectedFunction", it[3].name) + } + } + } + + private fun testVisibility(body: String, includedVisibility: Set, asserts: (List) -> Unit) { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + documentedVisibilities = includedVisibility + sourceRoots = listOf("src/") + } + } + } + + testInline( + """ + |/src/main/java/basic/JavaVisibilityTest.java + |package example; + | + $body + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = asserts + } + } + @ParameterizedTest @MethodSource(value = ["nonPublicPermutations", "publicPermutations"]) - fun `should include package private java class`(configuration: ConfigurationWithVisibility) { + fun `includeNonPublic - should include package private java class`(configuration: ConfigurationWithVisibility) { testInline( """ |/src/main/java/basic/VisibilityTest.java @@ -67,7 +254,8 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { false, false, false, - false + false, + DokkaDefaults.documentedVisibilities ) ) } @@ -85,7 +273,8 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { true, false, false, - false + false, + DokkaDefaults.documentedVisibilities ) ) } diff --git a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt index 1bb2d5d0..51ef4e83 100644 --- a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt @@ -1,8 +1,12 @@ package filter +import org.jetbrains.dokka.DokkaConfiguration.Visibility +import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.model.DClass import org.jetbrains.dokka.model.DEnum +import org.jetbrains.dokka.model.DModule import org.junit.jupiter.api.Assertions import org.junit.jupiter.api.Test import kotlin.test.assertEquals @@ -12,7 +16,394 @@ import kotlin.test.assertTrue class VisibilityFilterTest : BaseAbstractTest() { @Test - fun `public function with false global includeNonPublic`() { + fun `should document only public for defaults`() { + testVisibility( + """ + | val publicProperty: String = "publicProperty" + | private val privateProperty: String = "privateProperty" + | + | fun publicFun() { } + | private fun privateFun() { } + """.trimIndent(), + visibilities = DokkaDefaults.documentedVisibilities + ) { module -> + val pckg = module.first().packages.first() + pckg.properties.also { + assertEquals(1, it.size) + assertEquals("publicProperty", it[0].name) + } + pckg.functions.also { + assertEquals(1, it.size) + assertEquals("publicFun", it[0].name) + } + } + } + + @Test + fun `should document public`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | internal val noise: String = "noise" + | + | private val privateProperty: String = "privateProperty" + | + | fun publicFun() { } + | + | private fun privateFun() { } + | } + """.trimIndent(), + visibilities = setOf(Visibility.PUBLIC) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(1, it.size) + assertEquals("publicProperty", it[0].name) + } + clazz.functions.also { + assertEquals(1, it.size) + assertEquals("publicFun", it[0].name) + } + } + } + + @Test + fun `should document only private`() { + testVisibility( + """ + | public val noiseMember: String = "noise" + | internal fun noiseFun() { } + | class NoisePublicClass { } + | + | private val privateProperty: String = "privateProperty" + | private fun privateFun() { } + """.trimIndent(), + visibilities = setOf(Visibility.PRIVATE) + ) { module -> + val pckg = module.first().packages.first() + + assertTrue(pckg.classlikes.isEmpty()) + pckg.properties.also { + assertEquals(1, it.size) + assertEquals("privateProperty", it[0].name) + } + pckg.functions.also { + assertEquals(1, it.size) + assertEquals("privateFun", it[0].name) + } + } + } + + @Test + fun `should document only internal`() { + testVisibility( + """ + | public val noiseMember: String = "noise" + | private fun noiseFun() { } + | class NoisePublicClass { } + | + | internal val internalProperty: String = "privateProperty" + | internal fun internalFun() { } + """.trimIndent(), + visibilities = setOf(Visibility.INTERNAL) + ) { module -> + val pckg = module.first().packages.first() + + assertTrue(pckg.classlikes.isEmpty()) + pckg.properties.also { + assertEquals(1, it.size) + assertEquals("internalProperty", it[0].name) + } + pckg.functions.also { + assertEquals(1, it.size) + assertEquals("internalFun", it[0].name) + } + } + } + + @Test + fun `should document private within public class`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | internal val noise: String = "noise" + | + | private val privateProperty: String = "privateProperty" + | + | fun publicFun() { } + | + | private fun privateFun() { } + | } + """.trimIndent(), + visibilities = setOf(Visibility.PUBLIC, Visibility.PRIVATE) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("privateProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFun", it[0].name) + assertEquals("privateFun", it[1].name) + } + } + } + + @Test + fun `should document internal within public class`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | protected val noise: String = "noise" + | + | internal val internalProperty: String = "internalProperty" + | + | fun publicFun() { } + | + | internal fun internalFun() { } + | } + """.trimIndent(), + visibilities = setOf(Visibility.PUBLIC, Visibility.INTERNAL) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("internalProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFun", it[0].name) + assertEquals("internalFun", it[1].name) + } + } + } + + @Test + fun `should document protected within public class`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | internal val noise: String = "noise" + | + | protected val protectedProperty: String = "protectedProperty" + | + | fun publicFun() { } + | + | protected fun protectedFun() { } + | } + """.trimIndent(), + visibilities = setOf(Visibility.PUBLIC, Visibility.PROTECTED) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("protectedProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFun", it[0].name) + assertEquals("protectedFun", it[1].name) + } + } + } + + @Test + fun `should document all visibilities`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | + | private val privateProperty: String = "privateProperty" + | internal val internalProperty: String = "internalProperty" + | protected val protectedProperty: String = "protectedProperty" + | + | fun publicFun() { } + | + | private fun privateFun() { } + | internal fun internalFun() { } + | protected fun protectedFun() { } + | } + """.trimIndent(), + visibilities = setOf( + Visibility.PUBLIC, + Visibility.PRIVATE, + Visibility.PROTECTED, + Visibility.INTERNAL + ) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(4, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("privateProperty", it[1].name) + assertEquals("internalProperty", it[2].name) + assertEquals("protectedProperty", it[3].name) + } + clazz.functions.also { + assertEquals(4, it.size) + assertEquals("publicFun", it[0].name) + assertEquals("privateFun", it[1].name) + assertEquals("internalFun", it[2].name) + assertEquals("protectedFun", it[3].name) + } + } + } + + @Test + fun `should ignore visibility settings for another package`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + perPackageOptions = listOf( + PackageOptionsImpl( + matchingRegex = "other", + documentedVisibilities = setOf(Visibility.PRIVATE), + includeNonPublic = false, + reportUndocumented = false, + skipDeprecated = false, + suppress = false + ) + ) + sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + } + } + } + + testInline( + """ + |/src/main/kotlin/basic/Test.kt + |package example + | + | fun publicFun() { } + | + | private fun privateFun() { } + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = { + val functions = it.first().packages.first().functions + assertEquals(1, functions.size) + assertEquals("publicFun", functions[0].name) + } + } + } + + @Test + fun `should choose package visibility settings over global`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + documentedVisibilities = setOf(Visibility.INTERNAL) + perPackageOptions = listOf( + PackageOptionsImpl( + matchingRegex = "example", + documentedVisibilities = setOf(Visibility.PRIVATE), + includeNonPublic = false, + reportUndocumented = false, + skipDeprecated = false, + suppress = false + ) + ) + sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + } + } + } + + testInline( + """ + |/src/main/kotlin/basic/Test.kt + |package example + | + | internal fun internalFun() { } + | + | private fun privateFun() { } + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = { + val functions = it.first().packages.first().functions + assertEquals(1, functions.size) + assertEquals("privateFun", functions[0].name) + } + } + } + + @Test + fun `private setter should be hidden if only PUBLIC is documented`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + documentedVisibilities = setOf(Visibility.PUBLIC) + sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + } + } + } + + testInline( + """ + |/src/main/kotlin/basic/Test.kt + |package example + | + |var property: Int = 0 + |private set + | + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = { + Assertions.assertNull( + it.first().packages.first().properties.first().setter + ) + } + } + } + + @Test + fun `should choose new documentedVisibilities over deprecated includeNonPublic`() { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + includeNonPublic = true + documentedVisibilities = setOf(Visibility.INTERNAL) + sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + } + } + } + + testInline( + """ + |/src/main/kotlin/basic/Test.kt + |package example + | + | internal fun internalFun() { } + | + | private fun privateFun() { } + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = { + val functions = it.first().packages.first().functions + assertEquals(1, functions.size) + assertEquals("internalFun", functions[0].name) + } + } + } + + @Test + fun `includeNonPublic - public function with false global`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -43,7 +434,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `private function with false global includeNonPublic`() { + fun `includeNonPublic - private function with false global`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -74,7 +465,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `private function with true global includeNonPublic`() { + fun `includeNonPublic - private function with true global`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -136,7 +527,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `private function with false global true package includeNonPublic`() { + fun `includeNonPublic - private function with false global true package`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -148,7 +539,8 @@ class VisibilityFilterTest : BaseAbstractTest() { true, false, false, - false + false, + DokkaDefaults.documentedVisibilities ) ) } @@ -176,7 +568,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `private function with true global false package includeNonPublic`() { + fun `includeNonPublic - private function with true global false package`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -188,7 +580,8 @@ class VisibilityFilterTest : BaseAbstractTest() { false, false, false, - false + false, + DokkaDefaults.documentedVisibilities ) ) } @@ -216,7 +609,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `private typealias should be skipped`() { + fun `includeNonPublic - private typealias should be skipped`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -242,7 +635,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `internal property from enum should be skipped`() { + fun `includeNonPublic - internal property from enum should be skipped`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -281,7 +674,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `internal property from enum`() { + fun `includeNonPublic - internal property from enum`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -318,4 +711,33 @@ class VisibilityFilterTest : BaseAbstractTest() { } } } + + + private fun testVisibility( + body: String, + visibilities: Set, + asserts: (List) -> Unit + ) { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + documentedVisibilities = visibilities + sourceRoots = listOf("src/main/kotlin/basic/Test.kt") + } + } + } + + testInline( + """ + |/src/main/kotlin/basic/Test.kt + |package example + | + $body + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = asserts + } + } } diff --git a/plugins/base/src/test/kotlin/model/JavaTest.kt b/plugins/base/src/test/kotlin/model/JavaTest.kt index e473b352..886aa0be 100644 --- a/plugins/base/src/test/kotlin/model/JavaTest.kt +++ b/plugins/base/src/test/kotlin/model/JavaTest.kt @@ -1,5 +1,6 @@ package model +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.Platform import org.jetbrains.dokka.base.transformers.documentables.InheritorsInfo import org.jetbrains.dokka.links.* @@ -21,7 +22,12 @@ class JavaTest : AbstractModelTest("/src/main/kotlin/java/Test.java", "java") { sourceRoots = listOf("src/") analysisPlatform = Platform.jvm.toString() classpath += jvmStdlibPath!! - includeNonPublic = true + documentedVisibilities = setOf( + DokkaConfiguration.Visibility.PUBLIC, + DokkaConfiguration.Visibility.PRIVATE, + DokkaConfiguration.Visibility.PROTECTED, + DokkaConfiguration.Visibility.PACKAGE, + ) } } } diff --git a/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt index 6a3b2b6f..13e90f42 100644 --- a/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt @@ -1,5 +1,7 @@ package transformers +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.Platform import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest @@ -908,11 +910,13 @@ class ReportUndocumentedTransformerTest : BaseAbstractTest() { reportUndocumented: Boolean?, includeNonPublic: Boolean = true, skipDeprecated: Boolean = false, - suppress: Boolean = false + suppress: Boolean = false, + documentedVisibilities: Set = DokkaDefaults.documentedVisibilities ) = PackageOptionsImpl( matchingRegex = matchingRegex, reportUndocumented = reportUndocumented, includeNonPublic = includeNonPublic, + documentedVisibilities = documentedVisibilities, skipDeprecated = skipDeprecated, suppress = suppress ) diff --git a/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt index c6d46b1f..73f043bc 100644 --- a/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt @@ -1,5 +1,6 @@ package transformers +import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest @@ -181,6 +182,7 @@ class SuppressedByConfigurationDocumentableFilterTransformerTest : BaseAbstractT matchingRegex = matchingRegex, suppress = suppress, includeNonPublic = true, + documentedVisibilities = DokkaDefaults.documentedVisibilities, reportUndocumented = false, skipDeprecated = false ) diff --git a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt index 50d43e63..798a3f3b 100644 --- a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt +++ b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt @@ -1,5 +1,6 @@ package translators +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.model.* import org.junit.jupiter.api.Assertions.* import org.jetbrains.dokka.model.doc.CodeBlock @@ -232,13 +233,18 @@ class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() { } @Test - fun `derived properties with includeNonPublic`() { + fun `derived properties with non-public code included`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { sourceRoots = listOf("src/main/kotlin") - includeNonPublic = true + documentedVisibilities = setOf( + DokkaConfiguration.Visibility.PUBLIC, + DokkaConfiguration.Visibility.PRIVATE, + DokkaConfiguration.Visibility.PROTECTED, + DokkaConfiguration.Visibility.INTERNAL, + ) } } } @@ -471,7 +477,7 @@ class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() { @Test - fun `derived properties with no includeNonPublic`() { + fun `derived properties with only public code`() { val configuration = dokkaConfiguration { sourceSets { -- cgit