diff --git a/core/api/core.api b/core/api/core.api index 46a4c3a561..471f63142a 100644 --- a/core/api/core.api +++ b/core/api/core.api @@ -89,6 +89,7 @@ public abstract interface class org/jetbrains/dokka/DokkaConfiguration$DokkaSour public abstract fun getClasspath ()Ljava/util/List; public abstract fun getDependentSourceSets ()Ljava/util/Set; public abstract fun getDisplayName ()Ljava/lang/String; + public abstract fun getDocumentedVisibilities ()Ljava/util/Set; public abstract fun getExternalDocumentationLinks ()Ljava/util/Set; public abstract fun getIncludeNonPublic ()Z public abstract fun getIncludes ()Ljava/util/Set; @@ -117,6 +118,7 @@ public final class org/jetbrains/dokka/DokkaConfiguration$ExternalDocumentationL } public abstract interface class org/jetbrains/dokka/DokkaConfiguration$PackageOptions : java/io/Serializable { + public abstract fun getDocumentedVisibilities ()Ljava/util/Set; public abstract fun getIncludeNonPublic ()Z public abstract fun getMatchingRegex ()Ljava/lang/String; public abstract fun getReportUndocumented ()Ljava/lang/Boolean; @@ -143,6 +145,21 @@ public abstract interface class org/jetbrains/dokka/DokkaConfiguration$SourceLin public abstract fun getRemoteUrl ()Ljava/net/URL; } +public final class org/jetbrains/dokka/DokkaConfiguration$Visibility : java/lang/Enum { + public static final field Companion Lorg/jetbrains/dokka/DokkaConfiguration$Visibility$Companion; + public static final field INTERNAL Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; + public static final field PACKAGE Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; + public static final field PRIVATE Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; + public static final field PROTECTED Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; + public static final field PUBLIC Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; + public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; + public static fun values ()[Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; +} + +public final class org/jetbrains/dokka/DokkaConfiguration$Visibility$Companion { + public final fun fromString (Ljava/lang/String;)Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; +} + public abstract interface class org/jetbrains/dokka/DokkaConfigurationBuilder { public abstract fun build ()Ljava/lang/Object; } @@ -206,6 +223,7 @@ public final class org/jetbrains/dokka/DokkaDefaults { public static final field suppressObviousFunctions Z public final fun getAnalysisPlatform ()Lorg/jetbrains/dokka/Platform; public final fun getCacheRoot ()Ljava/io/File; + public final fun getDocumentedVisibilities ()Ljava/util/Set; public final fun getModuleName ()Ljava/lang/String; public final fun getModuleVersion ()Ljava/lang/String; public final fun getOutputDir ()Ljava/io/File; @@ -254,8 +272,8 @@ public final class org/jetbrains/dokka/DokkaSourceSetID : java/io/Serializable { } public final class org/jetbrains/dokka/DokkaSourceSetImpl : org/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet { - public fun (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;)V - public synthetic fun (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;)V + public synthetic fun (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun component1 ()Ljava/lang/String; public final fun component10 ()Z public final fun component11 ()Z @@ -270,6 +288,7 @@ public final class org/jetbrains/dokka/DokkaSourceSetImpl : org/jetbrains/dokka/ public final fun component2 ()Lorg/jetbrains/dokka/DokkaSourceSetID; public final fun component20 ()Ljava/util/Set; public final fun component21 ()Lorg/jetbrains/dokka/Platform; + public final fun component22 ()Ljava/util/Set; public final fun component3 ()Ljava/util/List; public final fun component4 ()Ljava/util/Set; public final fun component5 ()Ljava/util/Set; @@ -277,14 +296,15 @@ public final class org/jetbrains/dokka/DokkaSourceSetImpl : org/jetbrains/dokka/ public final fun component7 ()Ljava/util/Set; public final fun component8 ()Z public final fun component9 ()Z - public final fun copy (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;)Lorg/jetbrains/dokka/DokkaSourceSetImpl; - public static synthetic fun copy$default (Lorg/jetbrains/dokka/DokkaSourceSetImpl;Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;ILjava/lang/Object;)Lorg/jetbrains/dokka/DokkaSourceSetImpl; + public final fun copy (Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;)Lorg/jetbrains/dokka/DokkaSourceSetImpl; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/DokkaSourceSetImpl;Ljava/lang/String;Lorg/jetbrains/dokka/DokkaSourceSetID;Ljava/util/List;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;Ljava/util/Set;ZZZZILjava/util/Set;Ljava/util/List;Ljava/util/Set;Ljava/lang/String;Ljava/lang/String;ZZLjava/util/Set;Lorg/jetbrains/dokka/Platform;Ljava/util/Set;ILjava/lang/Object;)Lorg/jetbrains/dokka/DokkaSourceSetImpl; public fun equals (Ljava/lang/Object;)Z public fun getAnalysisPlatform ()Lorg/jetbrains/dokka/Platform; public fun getApiVersion ()Ljava/lang/String; public fun getClasspath ()Ljava/util/List; public fun getDependentSourceSets ()Ljava/util/Set; public fun getDisplayName ()Ljava/lang/String; + public fun getDocumentedVisibilities ()Ljava/util/Set; public fun getExternalDocumentationLinks ()Ljava/util/Set; public fun getIncludeNonPublic ()Z public fun getIncludes ()Ljava/util/Set; @@ -324,15 +344,17 @@ public final class org/jetbrains/dokka/ExternalDocumentationLinkImpl : org/jetbr } public final class org/jetbrains/dokka/PackageOptionsImpl : org/jetbrains/dokka/DokkaConfiguration$PackageOptions { - public fun (Ljava/lang/String;ZLjava/lang/Boolean;ZZ)V + public fun (Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;)V public final fun component1 ()Ljava/lang/String; public final fun component2 ()Z public final fun component3 ()Ljava/lang/Boolean; public final fun component4 ()Z public final fun component5 ()Z - public final fun copy (Ljava/lang/String;ZLjava/lang/Boolean;ZZ)Lorg/jetbrains/dokka/PackageOptionsImpl; - public static synthetic fun copy$default (Lorg/jetbrains/dokka/PackageOptionsImpl;Ljava/lang/String;ZLjava/lang/Boolean;ZZILjava/lang/Object;)Lorg/jetbrains/dokka/PackageOptionsImpl; + public final fun component6 ()Ljava/util/Set; + public final fun copy (Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;)Lorg/jetbrains/dokka/PackageOptionsImpl; + public static synthetic fun copy$default (Lorg/jetbrains/dokka/PackageOptionsImpl;Ljava/lang/String;ZLjava/lang/Boolean;ZZLjava/util/Set;ILjava/lang/Object;)Lorg/jetbrains/dokka/PackageOptionsImpl; public fun equals (Ljava/lang/Object;)Z + public fun getDocumentedVisibilities ()Ljava/util/Set; public fun getIncludeNonPublic ()Z public fun getMatchingRegex ()Ljava/lang/String; public fun getReportUndocumented ()Ljava/lang/Boolean; diff --git a/core/src/main/kotlin/DokkaBootstrapImpl.kt b/core/src/main/kotlin/DokkaBootstrapImpl.kt index 67dee9ae09..75c4c0afe9 100644 --- a/core/src/main/kotlin/DokkaBootstrapImpl.kt +++ b/core/src/main/kotlin/DokkaBootstrapImpl.kt @@ -23,9 +23,16 @@ fun parsePerPackageOptions(args: List): List = args.map val suppress = options.find { it.endsWith("suppress") }?.startsWith("+") ?: DokkaDefaults.suppress + val documentedVisibilities = options + .filter { it.matches(Regex("\\+visibility:.+")) } // matches '+visibility:' with at least one symbol after the semicolon + .map { DokkaConfiguration.Visibility.fromString(it.split(":")[1]) } + .toSet() + .ifEmpty { DokkaDefaults.documentedVisibilities } + PackageOptionsImpl( matchingRegex, includeNonPublic = privateApi, + documentedVisibilities = documentedVisibilities, reportUndocumented = reportUndocumented, skipDeprecated = !deprecated, suppress = suppress diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt index 56fe843751..f41c6273e1 100644 --- a/core/src/main/kotlin/configuration.kt +++ b/core/src/main/kotlin/configuration.kt @@ -19,6 +19,7 @@ object DokkaDefaults { const val delayTemplateSubstitution: Boolean = false const val includeNonPublic: Boolean = false + val documentedVisibilities: Set = setOf() const val reportUndocumented: Boolean = false const val skipEmptyPackages: Boolean = true const val skipDeprecated: Boolean = false @@ -122,6 +123,7 @@ interface DokkaConfiguration : Serializable { val dependentSourceSets: Set val samples: Set val includes: Set + @Deprecated(message = "Use [documentedVisibilities] property for a more flexible control over documented visibilities") val includeNonPublic: Boolean val reportUndocumented: Boolean val skipEmptyPackages: Boolean @@ -136,6 +138,38 @@ interface DokkaConfiguration : Serializable { val noJdkLink: Boolean val suppressedFiles: Set val analysisPlatform: Platform + val documentedVisibilities: Set + } + + enum class Visibility { + /** + * `public` modifier for Java, default visibility for Kotlin + */ + PUBLIC, + + /** + * `private` modifier for both Kotlin and Java + */ + PRIVATE, + + /** + * `protected` modifier for both Kotlin and Java + */ + PROTECTED, + + /** + * Kotlin-specific `internal` modifier + */ + INTERNAL, + + /** + * Java-specific package-private visibility (no modifier) + */ + PACKAGE; + + companion object { + fun fromString(value: String) = valueOf(value.toUpperCase()) + } } interface SourceLinkDefinition : Serializable { @@ -153,10 +187,12 @@ interface DokkaConfiguration : Serializable { interface PackageOptions : Serializable { val matchingRegex: String + @Deprecated(message = "Use [documentedVisibilities] property for a more flexible control over documented visibilities") val includeNonPublic: Boolean val reportUndocumented: Boolean? val skipDeprecated: Boolean val suppress: Boolean + val documentedVisibilities: Set } interface ExternalDocumentationLink : Serializable { diff --git a/core/src/main/kotlin/defaultConfiguration.kt b/core/src/main/kotlin/defaultConfiguration.kt index 743cc6c2ff..4d23ce687b 100644 --- a/core/src/main/kotlin/defaultConfiguration.kt +++ b/core/src/main/kotlin/defaultConfiguration.kt @@ -50,6 +50,7 @@ data class DokkaSourceSetImpl( override val noJdkLink: Boolean = DokkaDefaults.noJdkLink, override val suppressedFiles: Set = emptySet(), override val analysisPlatform: Platform = DokkaDefaults.analysisPlatform, + override val documentedVisibilities: Set = DokkaDefaults.documentedVisibilities, ) : DokkaSourceSet data class DokkaModuleDescriptionImpl( @@ -81,6 +82,7 @@ data class PackageOptionsImpl( override val reportUndocumented: Boolean?, override val skipDeprecated: Boolean, override val suppress: Boolean, + override val documentedVisibilities: Set, ) : DokkaConfiguration.PackageOptions diff --git a/core/test-api/api/test-api.api b/core/test-api/api/test-api.api index b1f6a381a4..8333567294 100644 --- a/core/test-api/api/test-api.api +++ b/core/test-api/api/test-api.api @@ -83,14 +83,15 @@ public abstract interface annotation class testApi/testRunner/DokkaConfiguration } public final class testApi/testRunner/DokkaSourceSetBuilder { - public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)V - public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V + public fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZLjava/util/Set;ZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;)V + public synthetic fun (Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/Set;Ljava/util/List;Ljava/util/List;ZLjava/util/Set;ZZZILjava/lang/String;Ljava/lang/String;ZZLjava/util/List;Ljava/lang/String;Ljava/util/List;Ljava/util/List;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V public final fun build ()Lorg/jetbrains/dokka/DokkaSourceSetImpl; public final fun getAnalysisPlatform ()Ljava/lang/String; public final fun getApiVersion ()Ljava/lang/String; public final fun getClasspath ()Ljava/util/List; public final fun getDependentSourceSets ()Ljava/util/Set; public final fun getDisplayName ()Ljava/lang/String; + public final fun getDocumentedVisibilities ()Ljava/util/Set; public final fun getExternalDocumentationLinks ()Ljava/util/List; public final fun getIncludeNonPublic ()Z public final fun getIncludes ()Ljava/util/List; @@ -112,6 +113,7 @@ public final class testApi/testRunner/DokkaSourceSetBuilder { public final fun setClasspath (Ljava/util/List;)V public final fun setDependentSourceSets (Ljava/util/Set;)V public final fun setDisplayName (Ljava/lang/String;)V + public final fun setDocumentedVisibilities (Ljava/util/Set;)V public final fun setExternalDocumentationLinks (Ljava/util/List;)V public final fun setIncludeNonPublic (Z)V public final fun setIncludes (Ljava/util/List;)V diff --git a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt index 33f45b0278..edc1eebcda 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt @@ -88,7 +88,9 @@ class DokkaSourceSetBuilder( var dependentSourceSets: Set = emptySet(), var samples: List = emptyList(), var includes: List = emptyList(), + @Deprecated(message = "Use [documentedVisibilities] property for a more flexible control over documented visibilities") var includeNonPublic: Boolean = false, + var documentedVisibilities: Set = emptySet(), var reportUndocumented: Boolean = false, var skipEmptyPackages: Boolean = false, var skipDeprecated: Boolean = false, @@ -112,6 +114,7 @@ class DokkaSourceSetBuilder( samples = samples.map(::File).toSet(), includes = includes.map(::File).toSet(), includeNonPublic = includeNonPublic, + documentedVisibilities = documentedVisibilities, reportUndocumented = reportUndocumented, skipEmptyPackages = skipEmptyPackages, skipDeprecated = skipDeprecated, @@ -137,6 +140,7 @@ val defaultSourceSet = DokkaSourceSetImpl( samples = emptySet(), includes = emptySet(), includeNonPublic = false, + documentedVisibilities = emptySet(), reportUndocumented = false, skipEmptyPackages = true, skipDeprecated = false, diff --git a/docs/src/doc/docs/user_guide/cli/usage.md b/docs/src/doc/docs/user_guide/cli/usage.md index 9bfcb6fb20..ee172d6a64 100644 --- a/docs/src/doc/docs/user_guide/cli/usage.md +++ b/docs/src/doc/docs/user_guide/cli/usage.md @@ -29,11 +29,12 @@ Dokka supports the following command line arguments: * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references) separated by `;` * `-samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag) separated by `;` * `-includes` - list of files containing the documentation for the module and individual packages separated by `;` - * `-includeNonPublic` - include protected and private code + * `-includeNonPublic` - **Deprecated**, prefer using `documentedVisibilities`. Include protected and private code + * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Possible values: `PUBLIC` (by default, can be omitted), `PRIVATE`, `PROTECTED`, `INTERNAL` (Kotlin-specific), `PACKAGE` (Java-specific package-private) * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation * `-reportUndocumented` - warn about undocumented members * `-noSkipEmptyPackages` - create index pages for empty packages - * `-packageOptions` - list of package options in format `matchingRegex,-deprecated,-privateApi,+reportUndocumented;matchingRegex, ...`, separated by `;` + * `-perPackageOptions` - list of package options in format `matchingRegex,-deprecated,-privateApi,+reportUndocumented;+visibility:PRIVATE;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 `=[#lineSuffix]` * `-noStdlibLink` - disable linking to online kotlin-stdlib documentation @@ -104,6 +105,7 @@ The content of JSON file ```dokkaConfiguration.json```: "Module.md" ], "includeNonPublic": false, + "documentedVisibilities": ["PUBLIC", "PRIVATE", "PROTECTED", "INTERNAL", "PACKAGE"], "reportUndocumented": false, "skipEmptyPackages": true, "skipDeprecated": false, diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md index cc36329d75..1d3d5eac60 100644 --- a/docs/src/doc/docs/user_guide/gradle/usage.md +++ b/docs/src/doc/docs/user_guide/gradle/usage.md @@ -100,9 +100,20 @@ val dokkaHtml by getting(DokkaTask::class) { // Used to remove a source set from documentation, test source sets are suppressed by default suppress.set(false) - // Use to include or exclude non public members + // Deprecated. Prefer using documentedVisibilities. includeNonPublic.set(false) + // A set of visibility modifiers that should be documented + documentedVisibilities.set( + setOf( + Visibility.PUBLIC, // Included by default, can be omitted + Visibility.PRIVATE, // Same for both Kotlin and Java + Visibility.PROTECTED, // Same for both Kotlin and Java + Visibility.INTERNAL, // Kotlin-specific internal modifier + Visibility.PACKAGE, // Java-specific package-private visibility + ) + ) + // Do not output deprecated members. Applies globally, can be overridden by packageOptions skipDeprecated.set(false) @@ -173,11 +184,22 @@ val dokkaHtml by getting(DokkaTask::class) { // Repeat for multiple packageOptions // If multiple packages match the same matchingRegex, the longuest matchingRegex will be used perPackageOption { - matchingRegex.set("kotlin($|\\.).*") // will match kotlin and all sub-packages of it - // All options are optional, default values are below: + // will match kotlin and all sub-packages of it + matchingRegex.set("kotlin($|\\.).*") + + // All options are optional skipDeprecated.set(false) reportUndocumented.set(true) // Emit warnings about not documented members - includeNonPublic.set(false) + includeNonPublic.set(false) // Deprecated, prefer using documentedVisibilities + documentedVisibilities.set( // Visibilities that should be included in the documentation + setOf( + Visibility.PUBLIC, // Included by default, can be omitted + Visibility.PRIVATE, // Same for both Kotlin and Java + Visibility.PROTECTED, // Same for both Kotlin and Java + Visibility.INTERNAL, // Kotlin-specific internal modifier + Visibility.PACKAGE, // Java-specific package-private visibility + ) + ) } // Suppress a package perPackageOption { diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md index 25ccabf00a..cb86d03191 100644 --- a/docs/src/doc/docs/user_guide/maven/usage.md +++ b/docs/src/doc/docs/user_guide/maven/usage.md @@ -73,6 +73,15 @@ The available configuration options are shown below: packages.md extra.md + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + @@ -148,9 +157,21 @@ The available configuration options are shown below: false + true + + false + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt index 8b3b4304f3..fcf17b31a0 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt @@ -21,9 +21,25 @@ 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 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 + } + + return documentedVisibilities.takeIf { it.isNotEmpty() }?.contains(visibility) ?: 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 e7c35a6688..78a1159ff1 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,11 @@ class ContentForSignaturesTest : BaseAbstractTest() { sourceSet { sourceRoots = listOf("src/") analysisPlatform = "jvm" - includeNonPublic = true + documentedVisibilities = setOf( + 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 4431d38337..5d833ffdfd 100644 --- a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt @@ -109,7 +109,8 @@ class DeprecationFilterTest : BaseAbstractTest() { true, false, true, - false + false, + emptySet() ) ) } @@ -147,7 +148,9 @@ class DeprecationFilterTest : BaseAbstractTest() { false, false, false, - false) + false, + emptySet() + ) ) } } diff --git a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt index 32c00e923d..4f98eb7cf2 100644 --- a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt @@ -1,17 +1,202 @@ package filter +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.DokkaConfigurationImpl 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 include 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 = setOf() + ) { 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 include private`() { + 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.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 include package private`() { + 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.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 include protected`() { + 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.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.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 +252,8 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { false, false, false, - false + false, + emptySet() ) ) } @@ -85,7 +271,8 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { true, false, false, - false + false, + emptySet() ) ) } diff --git a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt index ffefaaea39..c9886528cd 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 +import org.jetbrains.dokka.DokkaConfiguration.Visibility 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,285 @@ import kotlin.test.assertTrue class VisibilityFilterTest : BaseAbstractTest() { @Test - fun `public function with false global includeNonPublic`() { + fun `should not include non-public if no additional visibilities are provided`() { + testVisibility( + """ + | val publicProperty: String = "publicProperty" + | private val privateProperty: String = "privateProperty" + | + | fun publicFun() { } + | private fun privateFun() { } + """.trimIndent(), + includedVisibility = setOf() + ) { 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 private`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | internal val noise: String = "noise" + | + | private val privateProperty: String = "privateProperty" + | + | fun publicFun() { } + | + | private fun privateFun() { } + | } + """.trimIndent(), + includedVisibility = setOf(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`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | protected val noise: String = "noise" + | + | internal val internalProperty: String = "internalProperty" + | + | fun publicFun() { } + | + | internal fun internalFun() { } + | } + """.trimIndent(), + includedVisibility = setOf(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`() { + testVisibility( + """ + | class TestClass { + | val publicProperty: String = "publicProperty" + | internal val noise: String = "noise" + | + | protected val protectedProperty: String = "protectedProperty" + | + | fun publicFun() { } + | + | protected fun protectedFun() { } + | } + """.trimIndent(), + includedVisibility = setOf(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(), + includedVisibility = setOf( + 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 testFunction() { } + | + | private fun privateFun() { } + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = { + val functions = it.first().packages.first().functions + assertEquals(1, functions.size) + assertEquals("testFunction", 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 + | + | fun testFunction() { } + | + | internal fun internalFun() { } + | + | private fun privateFun() { } + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = { + val functions = it.first().packages.first().functions + assertEquals(2, functions.size) + assertEquals("testFunction", functions[0].name) + assertEquals("privateFun", functions[1].name) + } + } + } + + @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 + | + | fun testFunction() { } + | + | internal fun internalFun() { } + | + | private fun privateFun() { } + | + """.trimMargin(), + configuration + ) { + preMergeDocumentablesTransformationStage = { + val functions = it.first().packages.first().functions + assertEquals(2, functions.size) + assertEquals("testFunction", functions[0].name) + assertEquals("internalFun", functions[1].name) + } + } + } + + @Test + fun `includeNonPublic - public function with false global`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -43,7 +325,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 +356,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `private function with true global includeNonPublic`() { + fun `includeNonPublic - private function with true global`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -105,7 +387,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 { @@ -117,7 +399,8 @@ class VisibilityFilterTest : BaseAbstractTest() { true, false, false, - false + false, + emptySet() ) ) } @@ -145,7 +428,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 { @@ -157,7 +440,8 @@ class VisibilityFilterTest : BaseAbstractTest() { false, false, false, - false + false, + emptySet() ) ) } @@ -185,7 +469,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `private typealias should be skipped`() { + fun `includeNonPublic - private typealias should be skipped`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -211,7 +495,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 { @@ -250,7 +534,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `internal property from enum`() { + fun `includeNonPublic - internal property from enum`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -287,4 +571,29 @@ class VisibilityFilterTest : BaseAbstractTest() { } } } + + + private fun testVisibility(body: String, includedVisibility: Set, asserts: (List) -> Unit) { + val configuration = dokkaConfiguration { + sourceSets { + sourceSet { + documentedVisibilities = includedVisibility + 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 e473b352d9..26e8681326 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,11 @@ 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.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 6a3b2b6fa6..65e05eeb5d 100644 --- a/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt @@ -1,5 +1,6 @@ package transformers +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.Platform import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest @@ -908,11 +909,13 @@ class ReportUndocumentedTransformerTest : BaseAbstractTest() { reportUndocumented: Boolean?, includeNonPublic: Boolean = true, skipDeprecated: Boolean = false, - suppress: Boolean = false + suppress: Boolean = false, + documentedVisibilities: Set = emptySet() ) = 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 c6d46b1f6c..897cd3d02a 100644 --- a/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt @@ -181,6 +181,7 @@ class SuppressedByConfigurationDocumentableFilterTransformerTest : BaseAbstractT matchingRegex = matchingRegex, suppress = suppress, includeNonPublic = true, + documentedVisibilities = emptySet(), 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 50d43e636e..c6bd7bf9e4 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,17 @@ 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.PRIVATE, + DokkaConfiguration.Visibility.PROTECTED, + DokkaConfiguration.Visibility.INTERNAL, + ) } } } @@ -471,13 +476,14 @@ class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() { @Test - fun `derived properties with no includeNonPublic`() { + fun `derived properties with only public code`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { sourceRoots = listOf("src/main/kotlin") includeNonPublic = false + documentedVisibilities = emptySet() } } } diff --git a/runners/cli/api/cli.api b/runners/cli/api/cli.api index b7ea94ffa5..e1e52c0572 100644 --- a/runners/cli/api/cli.api +++ b/runners/cli/api/cli.api @@ -53,6 +53,13 @@ public final class org/jetbrains/dokka/ArgTypeSourceLinkDefinition : kotlinx/cli public fun getDescription ()Ljava/lang/String; } +public final class org/jetbrains/dokka/ArgTypeVisibility : kotlinx/cli/ArgType { + public static final field INSTANCE Lorg/jetbrains/dokka/ArgTypeVisibility; + public synthetic fun convert (Ljava/lang/String;Ljava/lang/String;)Ljava/lang/Object; + public fun convert (Ljava/lang/String;Ljava/lang/String;)Lorg/jetbrains/dokka/DokkaConfiguration$Visibility; + public fun getDescription ()Ljava/lang/String; +} + public final class org/jetbrains/dokka/GlobalArguments : org/jetbrains/dokka/DokkaConfiguration { public fun ([Ljava/lang/String;)V public fun getCacheRoot ()Ljava/io/File; diff --git a/runners/cli/src/main/kotlin/cli/main.kt b/runners/cli/src/main/kotlin/cli/main.kt index 7a7a558278..ccbc9ed1bf 100644 --- a/runners/cli/src/main/kotlin/cli/main.kt +++ b/runners/cli/src/main/kotlin/cli/main.kt @@ -204,6 +204,11 @@ private fun parseSourceSet(moduleName: String, args: Array): DokkaConfig val includeNonPublic: Boolean by parser.option(ArgType.Boolean, description = "Include non public") .default(DokkaDefaults.includeNonPublic) + val documentedVisibilities by parser.option( + ArgTypeVisibility, + description = "Visibilities to be documented (allows multiple values separated by the semicolon `;`)" + ).delimiter(";") + val reportUndocumented by parser.option(ArgType.Boolean, description = "Report undocumented members") .default(DokkaDefaults.reportUndocumented) @@ -290,6 +295,7 @@ private fun parseSourceSet(moduleName: String, args: Array): DokkaConfig override val noStdlibLink = noStdlibLink override val noJdkLink = noJdkLink override val suppressedFiles = suppressedFiles.toMutableSet() + override val documentedVisibilities: Set = documentedVisibilities.toSet() } } @@ -305,6 +311,13 @@ object ArgTypePlatform : ArgType(true) { get() = "{ String that represents platform }" } +object ArgTypeVisibility : ArgType(true) { + override fun convert(value: kotlin.String, name: kotlin.String) = DokkaConfiguration.Visibility.fromString(value) + override val description: kotlin.String + get() = "{ String that represents a visibility modifier. " + + "Possible values: ${DokkaConfiguration.Visibility.values().joinToString(separator = ", ")} }" +} + object ArgTypePlugin : ArgType(true) { override fun convert( value: kotlin.String, diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt index de8eed770f..abaa25369c 100644 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt +++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/GradleDokkaSourceSetBuilder.kt @@ -59,6 +59,10 @@ open class GradleDokkaSourceSetBuilder( val includeNonPublic: Property = project.objects.safeProperty() .safeConvention(DokkaDefaults.includeNonPublic) + @Input + val documentedVisibilities: SetProperty = project.objects.setProperty() + .convention(DokkaDefaults.documentedVisibilities) + @Input val reportUndocumented: Property = project.objects.safeProperty() .safeConvention(DokkaDefaults.reportUndocumented) 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 9b6108b870..f15a6462ac 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 @@ -4,8 +4,11 @@ package org.jetbrains.dokka.gradle import org.gradle.api.Project import org.gradle.api.provider.Property +import org.gradle.api.provider.SetProperty import org.gradle.api.tasks.Input import org.gradle.api.tasks.Internal +import org.gradle.kotlin.dsl.setProperty +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.DokkaConfigurationBuilder import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl @@ -22,6 +25,10 @@ class GradlePackageOptionsBuilder( val includeNonPublic: Property = project.objects.safeProperty() .safeConvention(DokkaDefaults.includeNonPublic) + @Input + val documentedVisibilities: SetProperty = project.objects.setProperty() + .convention(DokkaDefaults.documentedVisibilities) + @Input val reportUndocumented: Property = project.objects.safeProperty() .safeConvention(DokkaDefaults.reportUndocumented) @@ -37,6 +44,7 @@ class GradlePackageOptionsBuilder( override fun build(): PackageOptionsImpl = PackageOptionsImpl( matchingRegex = checkNotNull(matchingRegex.getSafe()) { "prefix not specified" }, includeNonPublic = includeNonPublic.getSafe(), + documentedVisibilities = documentedVisibilities.getSafe(), reportUndocumented = reportUndocumented.getSafe(), skipDeprecated = skipDeprecated.getSafe(), suppress = suppress.getSafe() diff --git a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt index 74e3d16d38..56c3f0716a 100644 --- a/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt +++ b/runners/gradle-plugin/src/main/kotlin/org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt @@ -13,6 +13,7 @@ internal fun GradleDokkaSourceSetBuilder.toDokkaSourceSetImpl(): DokkaSourceSetI samples = samples.toSet(), includes = includes.toSet(), includeNonPublic = includeNonPublic.getSafe(), + documentedVisibilities = documentedVisibilities.getSafe(), reportUndocumented = reportUndocumented.getSafe(), skipEmptyPackages = skipEmptyPackages.getSafe(), skipDeprecated = skipDeprecated.getSafe(), diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt index 685068766e..877d3b37a7 100644 --- a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt +++ b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationJsonTest.kt @@ -39,6 +39,7 @@ class DokkaConfigurationJsonTest { packageOption.includeNonPublic by true packageOption.reportUndocumented by true packageOption.skipDeprecated by true + packageOption.documentedVisibilities by setOf(DokkaConfiguration.Visibility.PRIVATE) } } } diff --git a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt index 2887f9579b..811f7736b5 100644 --- a/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt +++ b/runners/gradle-plugin/src/test/kotlin/org/jetbrains/dokka/gradle/DokkaConfigurationSerializableTest.kt @@ -48,6 +48,7 @@ class DokkaConfigurationSerializableTest { packageOption.includeNonPublic by true packageOption.reportUndocumented by true packageOption.skipDeprecated by true + packageOption.documentedVisibilities by setOf(DokkaConfiguration.Visibility.PRIVATE) } } } 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 6216b5d7ee..949e494974 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 @@ -162,6 +162,22 @@ class GradleDokkaSourceSetBuilderTest { ) } + @Test + fun documentedVisibilities() { + val sourceSet = GradleDokkaSourceSetBuilder("", project) + assertEquals( + DokkaDefaults.documentedVisibilities, sourceSet.build().documentedVisibilities, + "Expected default value for ${GradleDokkaSourceSetBuilder::documentedVisibilities.name}" + ) + + val visibilities = setOf(DokkaConfiguration.Visibility.PRIVATE, DokkaConfiguration.Visibility.INTERNAL) + sourceSet.documentedVisibilities.set(visibilities) + assertEquals( + visibilities, sourceSet.build().documentedVisibilities, + "Expected to see previously set value for ${GradleDokkaSourceSetBuilder::includeNonPublic.name}" + ) + } + @Test fun reportUndocumented() { val sourceSet = GradleDokkaSourceSetBuilder("", project) @@ -261,6 +277,7 @@ class GradleDokkaSourceSetBuilderTest { PackageOptionsImpl( matchingRegex = matchingRegex, includeNonPublic = DokkaDefaults.includeNonPublic, + documentedVisibilities = DokkaDefaults.documentedVisibilities, reportUndocumented = DokkaDefaults.reportUndocumented, skipDeprecated = DokkaDefaults.skipDeprecated, suppress = DokkaDefaults.suppress diff --git a/runners/maven-plugin/api/maven-plugin.api b/runners/maven-plugin/api/maven-plugin.api index c45e325952..3b4ace568f 100644 --- a/runners/maven-plugin/api/maven-plugin.api +++ b/runners/maven-plugin/api/maven-plugin.api @@ -5,6 +5,7 @@ public abstract class org/jetbrains/dokka/maven/AbstractDokkaMojo : org/apache/m public final fun getCacheRoot ()Ljava/lang/String; public final fun getClasspath ()Ljava/util/List; public final fun getDisplayName ()Ljava/lang/String; + public final fun getDocumentedVisibilities ()Ljava/util/Set; public final fun getDokkaPlugins ()Ljava/util/List; public final fun getExternalDocumentationLinks ()Ljava/util/List; public final fun getFailOnWarning ()Z @@ -36,6 +37,7 @@ public abstract class org/jetbrains/dokka/maven/AbstractDokkaMojo : org/apache/m public final fun setCacheRoot (Ljava/lang/String;)V public final fun setClasspath (Ljava/util/List;)V public final fun setDisplayName (Ljava/lang/String;)V + public final fun setDocumentedVisibilities (Ljava/util/Set;)V public final fun setDokkaPlugins (Ljava/util/List;)V public final fun setExternalDocumentationLinks (Ljava/util/List;)V public final fun setFailOnWarning (Z)V @@ -66,11 +68,13 @@ public abstract class org/jetbrains/dokka/maven/AbstractDokkaMojo : org/apache/m public final class org/jetbrains/dokka/maven/AbstractDokkaMojo$PackageOptions : org/jetbrains/dokka/DokkaConfiguration$PackageOptions { public fun ()V + public fun getDocumentedVisibilities ()Ljava/util/Set; public fun getIncludeNonPublic ()Z public fun getMatchingRegex ()Ljava/lang/String; public fun getReportUndocumented ()Ljava/lang/Boolean; public fun getSkipDeprecated ()Z public fun getSuppress ()Z + public fun setDocumentedVisibilities (Ljava/util/Set;)V public fun setIncludeNonPublic (Z)V public fun setMatchingRegex (Ljava/lang/String;)V public fun setReportUndocumented (Z)V diff --git a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt index 58039ab970..b73dd4060b 100644 --- a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt +++ b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt @@ -78,6 +78,9 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List = DokkaDefaults.documentedVisibilities } @Parameter @@ -152,6 +155,9 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List = DokkaDefaults.documentedVisibilities + @Parameter var failOnWarning: Boolean = DokkaDefaults.failOnWarning @@ -198,6 +204,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List