add matchingRegex as a simpler replacement for prefix

Kotlin · Nov 11, 2020 · a5081a8 · a5081a8
1 parent 07e4367
commit a5081a8
Show file tree

Hide file tree

Showing 16 changed files with 44 additions and 42 deletions.
diff --git a/core/src/main/kotlin/DokkaBootstrapImpl.kt b/core/src/main/kotlin/DokkaBootstrapImpl.kt
@@ -7,8 +7,8 @@ import java.util.function.BiConsumer
 
 
 fun parsePerPackageOptions(args: List<String>): List<PackageOptions> = args.map { it.split(",") }.map {
-    val prefix = it.first()
-    if (prefix == "")
+    val matchingRegex = it.first()
+    if (matchingRegex == ".*")
         throw IllegalArgumentException(
             "Please do not register packageOptions with all match pattern, use global settings instead"
         )
@@ -28,7 +28,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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -170,15 +170,15 @@ dokkaHtml {
             // Allows to customize documentation generation options on a per-package basis
             // Repeat for multiple packageOptions
             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 
                 includeNonPublic.set(false)
             }
             // 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
@@ -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/...ase/src/main/kotlin/transformers/documentables/DeprecatedDocumentableFilterTransformer.kt b/...ase/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/...ase/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt b/...ase/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
@@ -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
@@ -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
@@ -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
@@ -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/...s/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradlePackageOptionsBuilder.kt b/...s/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/...adle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilderTest.kt b/...adle-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
@@ -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,