diff options
16 files changed, 44 insertions, 45 deletions
diff --git a/core/src/main/kotlin/DokkaBootstrapImpl.kt b/core/src/main/kotlin/DokkaBootstrapImpl.kt index 584d8b8c..6d6d8698 100644 --- a/core/src/main/kotlin/DokkaBootstrapImpl.kt +++ b/core/src/main/kotlin/DokkaBootstrapImpl.kt @@ -7,11 +7,7 @@ import java.util.function.BiConsumer fun parsePerPackageOptions(args: List<String>): List<PackageOptions> = args.map { it.split(",") }.map { - val prefix = it.first() - if (prefix == "") - throw IllegalArgumentException( - "Please do not register packageOptions with all match pattern, use global settings instead" - ) + val matchingRegex = it.first() val args = it.subList(1, it.size) @@ -28,7 +24,7 @@ fun parsePerPackageOptions(args: List<String>): List<PackageOptions> = args.map ?: DokkaDefaults.suppress PackageOptionsImpl( - prefix, + matchingRegex, includeNonPublic = privateApi, reportUndocumented = reportUndocumented, skipDeprecated = !deprecated, diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt index bc097ae4..15525152 100644 --- a/core/src/main/kotlin/configuration.kt +++ b/core/src/main/kotlin/configuration.kt @@ -144,7 +144,7 @@ interface DokkaConfiguration : Serializable { } interface PackageOptions : Serializable { - val prefix: String + val matchingRegex: String val includeNonPublic: Boolean val reportUndocumented: Boolean? val skipDeprecated: Boolean diff --git a/core/src/main/kotlin/defaultConfiguration.kt b/core/src/main/kotlin/defaultConfiguration.kt index 61c86c5a..240fb110 100644 --- a/core/src/main/kotlin/defaultConfiguration.kt +++ b/core/src/main/kotlin/defaultConfiguration.kt @@ -71,7 +71,7 @@ data class SourceLinkDefinitionImpl( } data class PackageOptionsImpl( - override val prefix: String, + override val matchingRegex: String, override val includeNonPublic: Boolean, override val reportUndocumented: Boolean?, override val skipDeprecated: Boolean, diff --git a/core/src/main/kotlin/transformers/documentation/PreMergeDocumentableTransformer.kt b/core/src/main/kotlin/transformers/documentation/PreMergeDocumentableTransformer.kt index 60769e9b..21548a4c 100644 --- a/core/src/main/kotlin/transformers/documentation/PreMergeDocumentableTransformer.kt +++ b/core/src/main/kotlin/transformers/documentation/PreMergeDocumentableTransformer.kt @@ -28,8 +28,8 @@ fun PreMergeDocumentableTransformer.sourceSet(documentable: Documentable): Dokka fun PreMergeDocumentableTransformer.perPackageOptions(documentable: Documentable): PackageOptions? { val packageName = documentable.dri.packageName ?: return null return sourceSet(documentable).perPackageOptions - .sortedByDescending { packageOptions -> packageOptions.prefix.length } - .firstOrNull { packageOptions -> packageName.startsWith(packageOptions.prefix) } + .sortedByDescending { packageOptions -> packageOptions.matchingRegex.length } + .firstOrNull { packageOptions -> Regex(packageOptions.matchingRegex).matches(packageName) } } fun <T> PreMergeDocumentableTransformer.source(documentable: T) where T : Documentable, T : WithSources = diff --git a/docs/src/doc/docs/user_guide/cli/usage.md b/docs/src/doc/docs/user_guide/cli/usage.md index 6f9ca84a..1f6b1124 100644 --- a/docs/src/doc/docs/user_guide/cli/usage.md +++ b/docs/src/doc/docs/user_guide/cli/usage.md @@ -31,7 +31,7 @@ Dokka supports the following command line arguments: * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation * `-reportUndocumented` - warn about undocumented members * `-skipEmptyPackages` - do not create index pages for empty packages - * `-packageOptions` - list of package options in format `prefix,-deprecated,-privateApi,+reportUndocumented;prefix, ...`, separated by `;` + * `-packageOptions` - list of package options in format `matchingRegex,-deprecated,-privateApi,+reportUndocumented;matchingRegex, ...`, separated by `;` * `-links` - list of external documentation links in format `url^packageListUrl^^url2...`, separated by `;` * `-srcLink` - mapping between a source directory and a Web site for browsing the code in format `<path>=<url>[#lineSuffix]` * `-noStdlibLink` - disable linking to online kotlin-stdlib documentation diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md index 5ca0eb30..cea1f80e 100644 --- a/docs/src/doc/docs/user_guide/gradle/usage.md +++ b/docs/src/doc/docs/user_guide/gradle/usage.md @@ -169,8 +169,9 @@ dokkaHtml { // Allows to customize documentation generation options on a per-package basis // Repeat for multiple packageOptions + // If multiple packages match the same matchingRegex, the longuest matchingRegex will be used perPackageOption { - prefix.set("kotlin") // will match kotlin and all sub-packages of it + matchingRegex.set("kotlin($|\\.).*") // will match kotlin and all sub-packages of it // All options are optional, default values are below: skipDeprecated.set(false) reportUndocumented.set(true) // Emit warnings about not documented members @@ -178,7 +179,7 @@ dokkaHtml { } // Suppress a package perPackageOption { - prefix.set("kotlin.internal") // will match kotlin.internal and all sub-packages of it + matchingRegex.set(".*\.internal.*") // will match all .internal packages and sub-packages suppress.set(true) } } diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md index 812737fa..feb53048 100644 --- a/docs/src/doc/docs/user_guide/maven/usage.md +++ b/docs/src/doc/docs/user_guide/maven/usage.md @@ -142,7 +142,7 @@ The available configuration options are shown below: <perPackageOptions> <packageOptions> <!-- Will match kotlin and all sub-packages of it --> - <prefix>kotlin</prefix> + <matchingRegex>kotlin($|\.).*</matchingRegex> <!-- All options are optional, default values are below: --> <skipDeprecated>false</skipDeprecated> diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DeprecatedDocumentableFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/DeprecatedDocumentableFilterTransformer.kt index 80696cbf..0f7795e6 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/DeprecatedDocumentableFilterTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/DeprecatedDocumentableFilterTransformer.kt @@ -24,7 +24,7 @@ class DeprecatedDocumentableFilterTransformer(val context: DokkaContext) : PreMe fun <T> T.isAllowedInPackage(): Boolean where T : WithExtraProperties<T>, T : Documentable { val packageName = this.dri.packageName val condition = packageName != null && packageOptions.firstOrNull { - packageName.startsWith(it.prefix) + Regex(it.matchingRegex).matches(packageName) }?.skipDeprecated ?: globalOptions.skipDeprecated diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt index 57faeefb..1bc7a533 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt @@ -23,7 +23,7 @@ class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMe is JavaVisibility.Default, is KotlinVisibility.Public -> true else -> packageName != null - && packageOptions.firstOrNull { packageName.startsWith(it.prefix) }?.includeNonPublic + && packageOptions.firstOrNull { Regex(it.matchingRegex).matches(packageName) }?.includeNonPublic ?: globalOptions.includeNonPublic } diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt index 2608d9ba..a8fabc95 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/ReportUndocumentedTransformer.kt @@ -158,7 +158,7 @@ internal class ReportUndocumentedTransformer : DocumentableTransformer { ): DokkaConfiguration.PackageOptions? { val packageName = documentable.dri.packageName ?: return null return dokkaSourceSet.perPackageOptions - .filter { packageOptions -> packageName.startsWith(packageOptions.prefix) } - .maxBy { packageOptions -> packageOptions.prefix.length } + .filter { packageOptions -> Regex(packageOptions.matchingRegex).matches(packageName) } + .maxBy { packageOptions -> packageOptions.matchingRegex.length } } } diff --git a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt index c8b9f2d4..b90b02af 100644 --- a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt @@ -104,11 +104,13 @@ class DeprecationFilterTest : AbstractCoreTest() { sourceRoots = listOf("src/main/kotlin/basic/Test.kt") skipDeprecated = false perPackageOptions = mutableListOf( - PackageOptionsImpl("example", + PackageOptionsImpl( + "example.*", true, false, true, - false) + false + ) ) } } diff --git a/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt index 265baa42..a87a8e7f 100644 --- a/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt @@ -380,7 +380,7 @@ class ReportUndocumentedTransformerTest : AbstractCoreTest() { sourceSets { sourceSet { perPackageOptions += packageOptions( - prefix = "sample", + matchingRegex = "sample.*", reportUndocumented = true, ) reportUndocumented = false @@ -410,11 +410,11 @@ class ReportUndocumentedTransformerTest : AbstractCoreTest() { sourceSets { sourceSet { perPackageOptions += packageOptions( - prefix = "sample", + matchingRegex = "sample.*", reportUndocumented = false, ) perPackageOptions += packageOptions( - prefix = "sample.enabled", + matchingRegex = "sample.enabled.*", reportUndocumented = true, ) reportUndocumented = false @@ -448,11 +448,11 @@ class ReportUndocumentedTransformerTest : AbstractCoreTest() { sourceSets { sourceSet { perPackageOptions += packageOptions( - prefix = "sample", + matchingRegex = "sample.*", reportUndocumented = true, ) perPackageOptions += packageOptions( - prefix = "sample.disabled", + matchingRegex = "sample.disabled.*", reportUndocumented = false, ) reportUndocumented = true @@ -904,13 +904,13 @@ class ReportUndocumentedTransformerTest : AbstractCoreTest() { } private fun packageOptions( - prefix: String, + matchingRegex: String, reportUndocumented: Boolean?, includeNonPublic: Boolean = true, skipDeprecated: Boolean = false, suppress: Boolean = false ) = PackageOptionsImpl( - prefix = prefix, + matchingRegex = matchingRegex, reportUndocumented = reportUndocumented, includeNonPublic = includeNonPublic, skipDeprecated = skipDeprecated, diff --git a/plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt index 93b36d2e..a4ce9230 100644 --- a/plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/SuppressedDocumentableFilterTransformerTest.kt @@ -16,8 +16,8 @@ class SuppressedDocumentableFilterTransformerTest : AbstractCoreTest() { sourceSet { sourceRoots = listOf("src") perPackageOptions = listOf( - packageOptions(prefix = "suppressed", suppress = true), - packageOptions(prefix = "default", suppress = false) + packageOptions(matchingRegex = "suppressed.*", suppress = true), + packageOptions(matchingRegex = "default.*", suppress = false) ) } } @@ -57,11 +57,11 @@ class SuppressedDocumentableFilterTransformerTest : AbstractCoreTest() { sourceSet { sourceRoots = listOf("src") perPackageOptions = listOf( - packageOptions(prefix = "parent.some", suppress = false), - packageOptions(prefix = "parent.some.suppressed", suppress = true), + packageOptions(matchingRegex = "parent.some.*", suppress = false), + packageOptions(matchingRegex = "parent.some.suppressed.*", suppress = true), - packageOptions(prefix = "parent.other", suppress = true), - packageOptions(prefix = "parent.other.default", suppress = false) + packageOptions(matchingRegex = "parent.other.*", suppress = true), + packageOptions(matchingRegex = "parent.other.default.*", suppress = false) ) } } @@ -175,10 +175,10 @@ class SuppressedDocumentableFilterTransformerTest : AbstractCoreTest() { } private fun packageOptions( - prefix: String, + matchingRegex: String, suppress: Boolean ) = PackageOptionsImpl( - prefix = prefix, + matchingRegex = matchingRegex, suppress = suppress, includeNonPublic = true, reportUndocumented = false, diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt index 6485c8ed..9b6108b8 100644 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt +++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt @@ -15,8 +15,8 @@ class GradlePackageOptionsBuilder( @Transient @get:Internal internal val project: Project ) : DokkaConfigurationBuilder<PackageOptionsImpl> { @Input - val prefix: Property<String> = project.objects.safeProperty<String>() - .safeConvention("") + val matchingRegex: Property<String> = project.objects.safeProperty<String>() + .safeConvention(".*") @Input val includeNonPublic: Property<Boolean> = project.objects.safeProperty<Boolean>() @@ -35,7 +35,7 @@ class GradlePackageOptionsBuilder( .safeConvention(DokkaDefaults.suppress) override fun build(): PackageOptionsImpl = PackageOptionsImpl( - prefix = checkNotNull(prefix.getSafe()) { "prefix not specified" }, + matchingRegex = checkNotNull(matchingRegex.getSafe()) { "prefix not specified" }, includeNonPublic = includeNonPublic.getSafe(), reportUndocumented = reportUndocumented.getSafe(), skipDeprecated = skipDeprecated.getSafe(), diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderTest.kt index 920c48b4..68642054 100644 --- a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderTest.kt +++ b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderTest.kt @@ -245,21 +245,21 @@ class GradleDokkaSourceSetBuilderTest { assertEquals(emptyList(), sourceSet.build().perPackageOptions, "Expected no default per package options") sourceSet.perPackageOptions.add(GradlePackageOptionsBuilder(project).apply { - this.prefix by "p1" + this.matchingRegex by "p1.*" }) sourceSet.perPackageOption { - it.prefix by "p2" + it.matchingRegex by "p2.*" } sourceSet.perPackageOption(project.closureOf<GradlePackageOptionsBuilder> { - this.prefix by "p3" + this.matchingRegex by "p3.*" }) assertEquals( - listOf("p1", "p2", "p3").map { prefix -> + listOf("p1.*", "p2.*", "p3.*").map { matchingRegex -> PackageOptionsImpl( - prefix = prefix, + matchingRegex = matchingRegex, includeNonPublic = DokkaDefaults.includeNonPublic, reportUndocumented = DokkaDefaults.reportUndocumented, skipDeprecated = DokkaDefaults.skipDeprecated, diff --git a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt index b03d2811..00ace0f9 100644 --- a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt +++ b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt @@ -66,7 +66,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependenc class PackageOptions : DokkaConfiguration.PackageOptions { @Parameter - override var prefix: String = "" + override var matchingRegex: String = ".*" @Parameter override var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic @@ -203,7 +203,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependenc sourceLinks = sourceLinks.map { SourceLinkDefinitionImpl(it.path, URL(it.url), it.lineSuffix) }.toSet(), perPackageOptions = perPackageOptions.map { PackageOptionsImpl( - prefix = it.prefix, + matchingRegex = it.matchingRegex, includeNonPublic = it.includeNonPublic, reportUndocumented = it.reportUndocumented, skipDeprecated = it.skipDeprecated, |