From 232d8a4bb636ad0bf6b18fe36d9968255c739bd9 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Mon, 13 Dec 2021 21:11:40 +0300 Subject: [PATCH 1/7] Introduce `documentedVisibilities` setting --- core/api/core.api | 36 +- core/src/main/kotlin/DokkaBootstrapImpl.kt | 7 + core/src/main/kotlin/configuration.kt | 36 ++ core/src/main/kotlin/defaultConfiguration.kt | 2 + core/test-api/api/test-api.api | 6 +- .../TestDokkaConfigurationBuilder.kt | 4 + docs/src/doc/docs/user_guide/cli/usage.md | 6 +- docs/src/doc/docs/user_guide/gradle/usage.md | 30 +- docs/src/doc/docs/user_guide/maven/usage.md | 21 ++ ...DocumentableVisibilityFilterTransformer.kt | 22 +- .../signatures/ContentForSignaturesTest.kt | 7 +- .../kotlin/filter/DeprecationFilterTest.kt | 7 +- .../kotlin/filter/JavaVisibilityFilterTest.kt | 193 +++++++++- .../kotlin/filter/VisibilityFilterTest.kt | 329 +++++++++++++++++- .../base/src/test/kotlin/model/JavaTest.kt | 7 +- .../ReportUndocumentedTransformerTest.kt | 5 +- ...rationDocumentableFilterTransformerTest.kt | 1 + ...tDescriptorToDocumentableTranslatorTest.kt | 12 +- runners/cli/api/cli.api | 7 + runners/cli/src/main/kotlin/cli/main.kt | 13 + .../gradle/GradleDokkaSourceSetBuilder.kt | 4 + .../gradle/GradlePackageOptionsBuilder.kt | 8 + .../dokka/gradle/toDokkaSourceSetImpl.kt | 1 + .../gradle/DokkaConfigurationJsonTest.kt | 1 + .../DokkaConfigurationSerializableTest.kt | 1 + .../gradle/GradleDokkaSourceSetBuilderTest.kt | 17 + runners/maven-plugin/api/maven-plugin.api | 4 + .../maven-plugin/src/main/kotlin/DokkaMojo.kt | 8 + 28 files changed, 756 insertions(+), 39 deletions(-) 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 bd39b04062..83f7141bef 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 1bb2d5d002..d3c24b94c5 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 { @@ -136,7 +418,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 +430,8 @@ class VisibilityFilterTest : BaseAbstractTest() { true, false, false, - false + false, + emptySet() ) ) } @@ -176,7 +459,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 +471,8 @@ class VisibilityFilterTest : BaseAbstractTest() { false, false, false, - false + false, + emptySet() ) ) } @@ -216,7 +500,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 +526,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 +565,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `internal property from enum`() { + fun `includeNonPublic - internal property from enum`() { val configuration = dokkaConfiguration { sourceSets { sourceSet { @@ -318,4 +602,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 Date: Wed, 15 Dec 2021 18:52:09 +0300 Subject: [PATCH 2/7] Remove hardcoded doc generation for Visibility.PUBLIC, correct tests --- core/src/main/kotlin/configuration.kt | 2 +- .../TestDokkaConfigurationBuilder.kt | 4 +- docs/src/doc/docs/user_guide/cli/usage.md | 2 +- docs/src/doc/docs/user_guide/gradle/usage.md | 4 +- docs/src/doc/docs/user_guide/maven/usage.md | 4 +- ...DocumentableVisibilityFilterTransformer.kt | 10 +- .../signatures/ContentForSignaturesTest.kt | 1 + .../kotlin/filter/DeprecationFilterTest.kt | 5 +- .../kotlin/filter/JavaVisibilityFilterTest.kt | 22 +-- .../kotlin/filter/VisibilityFilterTest.kt | 134 ++++++++++++++---- .../base/src/test/kotlin/model/JavaTest.kt | 1 + .../ReportUndocumentedTransformerTest.kt | 3 +- ...rationDocumentableFilterTransformerTest.kt | 3 +- ...tDescriptorToDocumentableTranslatorTest.kt | 2 +- runners/cli/src/main/kotlin/cli/main.kt | 1 + 15 files changed, 147 insertions(+), 51 deletions(-) diff --git a/core/src/main/kotlin/configuration.kt b/core/src/main/kotlin/configuration.kt index f41c6273e1..46b338d241 100644 --- a/core/src/main/kotlin/configuration.kt +++ b/core/src/main/kotlin/configuration.kt @@ -19,7 +19,7 @@ object DokkaDefaults { const val delayTemplateSubstitution: Boolean = false const val includeNonPublic: Boolean = false - val documentedVisibilities: Set = setOf() + val documentedVisibilities: Set = setOf(DokkaConfiguration.Visibility.PUBLIC) const val reportUndocumented: Boolean = false const val skipEmptyPackages: Boolean = true const val skipDeprecated: Boolean = false 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 edc1eebcda..804e02ce2b 100644 --- a/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt +++ b/core/test-api/src/main/kotlin/testApi/testRunner/TestDokkaConfigurationBuilder.kt @@ -90,7 +90,7 @@ class DokkaSourceSetBuilder( 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 documentedVisibilities: Set = DokkaDefaults.documentedVisibilities, var reportUndocumented: Boolean = false, var skipEmptyPackages: Boolean = false, var skipDeprecated: Boolean = false, @@ -140,7 +140,7 @@ val defaultSourceSet = DokkaSourceSetImpl( samples = emptySet(), includes = emptySet(), includeNonPublic = false, - documentedVisibilities = emptySet(), + documentedVisibilities = DokkaDefaults.documentedVisibilities, 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 ee172d6a64..65c4f93007 100644 --- a/docs/src/doc/docs/user_guide/cli/usage.md +++ b/docs/src/doc/docs/user_guide/cli/usage.md @@ -30,7 +30,7 @@ Dokka supports the following command line arguments: * `-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` - **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) + * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Possible values: `PUBLIC`, `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 diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md index 1d3d5eac60..5f810cb79a 100644 --- a/docs/src/doc/docs/user_guide/gradle/usage.md +++ b/docs/src/doc/docs/user_guide/gradle/usage.md @@ -106,7 +106,7 @@ val dokkaHtml by getting(DokkaTask::class) { // A set of visibility modifiers that should be documented documentedVisibilities.set( setOf( - Visibility.PUBLIC, // Included by default, can be omitted + Visibility.PUBLIC, // Same for both Kotlin and Java Visibility.PRIVATE, // Same for both Kotlin and Java Visibility.PROTECTED, // Same for both Kotlin and Java Visibility.INTERNAL, // Kotlin-specific internal modifier @@ -193,7 +193,7 @@ val dokkaHtml by getting(DokkaTask::class) { 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.PUBLIC, // Same for both Kotlin and Java Visibility.PRIVATE, // Same for both Kotlin and Java Visibility.PROTECTED, // Same for both Kotlin and Java Visibility.INTERNAL, // Kotlin-specific internal modifier diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md index cb86d03191..cd8d890b56 100644 --- a/docs/src/doc/docs/user_guide/maven/usage.md +++ b/docs/src/doc/docs/user_guide/maven/usage.md @@ -76,7 +76,7 @@ The available configuration options are shown below: - PUBLIC + PUBLIC PRIVATE PROTECTED INTERNAL @@ -166,7 +166,7 @@ The available configuration options are shown below: - PUBLIC + PUBLIC PRIVATE PROTECTED INTERNAL diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt index 83f7141bef..c15e2137c1 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,7 +21,7 @@ class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMe ) { fun Visibility.isAllowedInPackage(packageName: String?) = when (this) { is JavaVisibility.Public, - is KotlinVisibility.Public -> true + is KotlinVisibility.Public -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PUBLIC) is JavaVisibility.Private, is KotlinVisibility.Private -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PRIVATE) is JavaVisibility.Protected, @@ -39,7 +40,12 @@ class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMe else -> globalOptions.documentedVisibilities to globalOptions.includeNonPublic } - return documentedVisibilities.takeIf { it.isNotEmpty() }?.contains(visibility) ?: includeNonPublic + val isDocumentedVisibilitiesOverridden = documentedVisibilities !== DokkaDefaults.documentedVisibilities + return if (isDocumentedVisibilitiesOverridden) { + documentedVisibilities.contains(visibility) + } else { + visibility == DokkaConfiguration.Visibility.PUBLIC || 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 78a1159ff1..c0f1ebfb8b 100644 --- a/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt +++ b/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt @@ -20,6 +20,7 @@ class ContentForSignaturesTest : BaseAbstractTest() { sourceRoots = listOf("src/") analysisPlatform = "jvm" 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 5d833ffdfd..e6f2c5e98d 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 @@ -110,7 +111,7 @@ class DeprecationFilterTest : BaseAbstractTest() { false, true, false, - emptySet() + DokkaDefaults.documentedVisibilities ) ) } @@ -149,7 +150,7 @@ class DeprecationFilterTest : BaseAbstractTest() { false, false, false, - emptySet() + DokkaDefaults.documentedVisibilities ) ) } diff --git a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt index 4f98eb7cf2..e6acec92ca 100644 --- a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt @@ -2,6 +2,7 @@ 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 @@ -15,7 +16,7 @@ import kotlin.test.assertEquals class JavaVisibilityFilterTest : BaseAbstractTest() { @Test - fun `should include nothing private if no visibilities are included`() { + fun `should document nothing private if no visibilities are included`() { testVisibility( """ | public class JavaVisibilityTest { @@ -26,7 +27,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { | private void privateFunction() { } | } """.trimIndent(), - includedVisibility = setOf() + includedVisibility = DokkaDefaults.documentedVisibilities ) { module -> val clazz = module.first().packages.first().classlikes.filterIsInstance().first() clazz.properties.also { @@ -41,7 +42,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { } @Test - fun `should include private`() { + fun `should document private within public class`() { testVisibility( """ | public class JavaVisibilityTest { @@ -54,7 +55,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { | private void privateFunction() { } | } """.trimIndent(), - includedVisibility = setOf(DokkaConfiguration.Visibility.PRIVATE) + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PRIVATE) ) { module -> val clazz = module.first().packages.first().classlikes.filterIsInstance().first() clazz.properties.also { @@ -71,7 +72,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { } @Test - fun `should include package private`() { + fun `should document package private within private class`() { testVisibility( """ | public class JavaVisibilityTest { @@ -84,7 +85,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { | void packagePrivateFunction() { } | } """.trimIndent(), - includedVisibility = setOf(DokkaConfiguration.Visibility.PACKAGE) + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PACKAGE) ) { module -> val clazz = module.first().packages.first().classlikes.filterIsInstance().first() clazz.properties.also { @@ -101,7 +102,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { } @Test - fun `should include protected`() { + fun `should document protected within public class`() { testVisibility( """ | public class JavaVisibilityTest { @@ -114,7 +115,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { | protected void protectedFunction() { } | } """.trimIndent(), - includedVisibility = setOf(DokkaConfiguration.Visibility.PROTECTED) + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PROTECTED) ) { module -> val clazz = module.first().packages.first().classlikes.filterIsInstance().first() clazz.properties.also { @@ -147,6 +148,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { | } """.trimIndent(), includedVisibility = setOf( + DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PRIVATE, DokkaConfiguration.Visibility.PROTECTED, DokkaConfiguration.Visibility.PACKAGE, @@ -253,7 +255,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { false, false, false, - emptySet() + DokkaDefaults.documentedVisibilities ) ) } @@ -272,7 +274,7 @@ class JavaVisibilityFilterTest : BaseAbstractTest() { false, false, false, - emptySet() + DokkaDefaults.documentedVisibilities ) ) } diff --git a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt index d3c24b94c5..df45cde173 100644 --- a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt @@ -1,7 +1,7 @@ package filter -import org.jetbrains.dokka.DokkaConfiguration 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 @@ -16,7 +16,7 @@ import kotlin.test.assertTrue class VisibilityFilterTest : BaseAbstractTest() { @Test - fun `should not include non-public if no additional visibilities are provided`() { + fun `should document only public for defaults`() { testVisibility( """ | val publicProperty: String = "publicProperty" @@ -25,7 +25,7 @@ class VisibilityFilterTest : BaseAbstractTest() { | fun publicFun() { } | private fun privateFun() { } """.trimIndent(), - includedVisibility = setOf() + visibilities = DokkaDefaults.documentedVisibilities ) { module -> val pckg = module.first().packages.first() pckg.properties.also { @@ -40,7 +40,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `should document private`() { + fun `should document public`() { testVisibility( """ | class TestClass { @@ -54,7 +54,90 @@ class VisibilityFilterTest : BaseAbstractTest() { | private fun privateFun() { } | } """.trimIndent(), - includedVisibility = setOf(Visibility.PRIVATE) + 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 { @@ -71,7 +154,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `should document internal`() { + fun `should document internal within public class`() { testVisibility( """ | class TestClass { @@ -85,7 +168,7 @@ class VisibilityFilterTest : BaseAbstractTest() { | internal fun internalFun() { } | } """.trimIndent(), - includedVisibility = setOf(Visibility.INTERNAL) + visibilities = setOf(Visibility.PUBLIC, Visibility.INTERNAL) ) { module -> val clazz = module.first().packages.first().classlikes.filterIsInstance().first() clazz.properties.also { @@ -102,7 +185,7 @@ class VisibilityFilterTest : BaseAbstractTest() { } @Test - fun `should document protected`() { + fun `should document protected within public class`() { testVisibility( """ | class TestClass { @@ -116,7 +199,7 @@ class VisibilityFilterTest : BaseAbstractTest() { | protected fun protectedFun() { } | } """.trimIndent(), - includedVisibility = setOf(Visibility.PROTECTED) + visibilities = setOf(Visibility.PUBLIC, Visibility.PROTECTED) ) { module -> val clazz = module.first().packages.first().classlikes.filterIsInstance().first() clazz.properties.also { @@ -150,7 +233,8 @@ class VisibilityFilterTest : BaseAbstractTest() { | protected fun protectedFun() { } | } """.trimIndent(), - includedVisibility = setOf( + visibilities = setOf( + Visibility.PUBLIC, Visibility.PRIVATE, Visibility.PROTECTED, Visibility.INTERNAL @@ -199,7 +283,7 @@ class VisibilityFilterTest : BaseAbstractTest() { |/src/main/kotlin/basic/Test.kt |package example | - | fun testFunction() { } + | fun publicFun() { } | | private fun privateFun() { } | @@ -209,7 +293,7 @@ class VisibilityFilterTest : BaseAbstractTest() { preMergeDocumentablesTransformationStage = { val functions = it.first().packages.first().functions assertEquals(1, functions.size) - assertEquals("testFunction", functions[0].name) + assertEquals("publicFun", functions[0].name) } } } @@ -240,8 +324,6 @@ class VisibilityFilterTest : BaseAbstractTest() { |/src/main/kotlin/basic/Test.kt |package example | - | fun testFunction() { } - | | internal fun internalFun() { } | | private fun privateFun() { } @@ -251,9 +333,8 @@ class VisibilityFilterTest : BaseAbstractTest() { ) { preMergeDocumentablesTransformationStage = { val functions = it.first().packages.first().functions - assertEquals(2, functions.size) - assertEquals("testFunction", functions[0].name) - assertEquals("privateFun", functions[1].name) + assertEquals(1, functions.size) + assertEquals("privateFun", functions[0].name) } } } @@ -275,8 +356,6 @@ class VisibilityFilterTest : BaseAbstractTest() { |/src/main/kotlin/basic/Test.kt |package example | - | fun testFunction() { } - | | internal fun internalFun() { } | | private fun privateFun() { } @@ -286,9 +365,8 @@ class VisibilityFilterTest : BaseAbstractTest() { ) { preMergeDocumentablesTransformationStage = { val functions = it.first().packages.first().functions - assertEquals(2, functions.size) - assertEquals("testFunction", functions[0].name) - assertEquals("internalFun", functions[1].name) + assertEquals(1, functions.size) + assertEquals("internalFun", functions[0].name) } } } @@ -431,7 +509,7 @@ class VisibilityFilterTest : BaseAbstractTest() { false, false, false, - emptySet() + DokkaDefaults.documentedVisibilities ) ) } @@ -472,7 +550,7 @@ class VisibilityFilterTest : BaseAbstractTest() { false, false, false, - emptySet() + DokkaDefaults.documentedVisibilities ) ) } @@ -604,11 +682,15 @@ class VisibilityFilterTest : BaseAbstractTest() { } - private fun testVisibility(body: String, includedVisibility: Set, asserts: (List) -> Unit) { + private fun testVisibility( + body: String, + visibilities: Set, + asserts: (List) -> Unit + ) { val configuration = dokkaConfiguration { sourceSets { sourceSet { - documentedVisibilities = includedVisibility + documentedVisibilities = visibilities sourceRoots = listOf("src/main/kotlin/basic/Test.kt") } } diff --git a/plugins/base/src/test/kotlin/model/JavaTest.kt b/plugins/base/src/test/kotlin/model/JavaTest.kt index 26e8681326..886aa0be46 100644 --- a/plugins/base/src/test/kotlin/model/JavaTest.kt +++ b/plugins/base/src/test/kotlin/model/JavaTest.kt @@ -23,6 +23,7 @@ class JavaTest : AbstractModelTest("/src/main/kotlin/java/Test.java", "java") { analysisPlatform = Platform.jvm.toString() classpath += jvmStdlibPath!! 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 65e05eeb5d..13e90f42d5 100644 --- a/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt +++ b/plugins/base/src/test/kotlin/transformers/ReportUndocumentedTransformerTest.kt @@ -1,6 +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 @@ -910,7 +911,7 @@ class ReportUndocumentedTransformerTest : BaseAbstractTest() { includeNonPublic: Boolean = true, skipDeprecated: Boolean = false, suppress: Boolean = false, - documentedVisibilities: Set = emptySet() + documentedVisibilities: Set = DokkaDefaults.documentedVisibilities ) = PackageOptionsImpl( matchingRegex = matchingRegex, reportUndocumented = reportUndocumented, diff --git a/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt b/plugins/base/src/test/kotlin/transformers/SuppressedByConfigurationDocumentableFilterTransformerTest.kt index 897cd3d02a..73f043bc21 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,7 +182,7 @@ class SuppressedByConfigurationDocumentableFilterTransformerTest : BaseAbstractT matchingRegex = matchingRegex, suppress = suppress, includeNonPublic = true, - documentedVisibilities = emptySet(), + 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 c6bd7bf9e4..798a3f3b8d 100644 --- a/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt +++ b/plugins/base/src/test/kotlin/translators/DefaultDescriptorToDocumentableTranslatorTest.kt @@ -240,6 +240,7 @@ class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() { sourceSet { sourceRoots = listOf("src/main/kotlin") documentedVisibilities = setOf( + DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PRIVATE, DokkaConfiguration.Visibility.PROTECTED, DokkaConfiguration.Visibility.INTERNAL, @@ -483,7 +484,6 @@ class DefaultDescriptorToDocumentableTranslatorTest : BaseAbstractTest() { sourceSet { sourceRoots = listOf("src/main/kotlin") includeNonPublic = false - documentedVisibilities = emptySet() } } } diff --git a/runners/cli/src/main/kotlin/cli/main.kt b/runners/cli/src/main/kotlin/cli/main.kt index ccbc9ed1bf..739539a997 100644 --- a/runners/cli/src/main/kotlin/cli/main.kt +++ b/runners/cli/src/main/kotlin/cli/main.kt @@ -296,6 +296,7 @@ private fun parseSourceSet(moduleName: String, args: Array): DokkaConfig override val noJdkLink = noJdkLink override val suppressedFiles = suppressedFiles.toMutableSet() override val documentedVisibilities: Set = documentedVisibilities.toSet() + .ifEmpty { DokkaDefaults.documentedVisibilities } } } From ec296941decf0255c9abd04f0c55e7a9d9bece5c Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 16 Dec 2021 15:21:47 +0300 Subject: [PATCH 3/7] Add maven, gradle and cli integration tests for documentedVisibilities --- docs/src/doc/docs/user_guide/cli/usage.md | 2 +- docs/src/doc/docs/user_guide/gradle/usage.md | 26 +++++---- docs/src/doc/docs/user_guide/maven/usage.md | 2 + .../src/main/kotlin/it/basic/PublicClass.kt | 9 +++ .../main/kotlin/it/internal/InternalClass.kt | 7 +++ .../VisiblePrivateClass.kt | 12 ++++ .../kotlin/it/protected/ProtectedClass.kt | 10 ++++ .../dokka/it/cli/CliIntegrationTest.kt | 54 ++++++++++++++++++ .../gradle/projects/it-basic/build.gradle.kts | 10 ++++ .../src/main/kotlin/it/basic/PublicClass.kt | 16 ++++++ .../main/kotlin/it/internal/InternalClass.kt | 2 +- .../VisiblePrivateClass.kt | 12 ++++ .../kotlin/it/protected/ProtectedClass.kt | 10 ++++ .../it/gradle/BasicGradleIntegrationTest.kt | 24 ++++++++ .../maven/projects/it-maven/pom.xml | 11 ++++ .../src/main/kotlin/it/basic/PublicClass.kt | 9 +++ .../main/kotlin/it/internal/InternalClass.kt | 7 +++ .../VisiblePrivateClass.kt | 12 ++++ .../kotlin/it/protected/ProtectedClass.kt | 10 ++++ .../dokka/it/maven/MavenIntegrationTest.kt | 29 ++++++++-- .../dokka/it/AbstractIntegrationTest.kt | 55 +++++++++++++++++++ 21 files changed, 312 insertions(+), 17 deletions(-) create mode 100644 integration-tests/cli/projects/it-cli/src/main/kotlin/it/internal/InternalClass.kt create mode 100644 integration-tests/cli/projects/it-cli/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt create mode 100644 integration-tests/cli/projects/it-cli/src/main/kotlin/it/protected/ProtectedClass.kt create mode 100644 integration-tests/gradle/projects/it-basic/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt create mode 100644 integration-tests/gradle/projects/it-basic/src/main/kotlin/it/protected/ProtectedClass.kt create mode 100644 integration-tests/maven/projects/it-maven/src/main/kotlin/it/internal/InternalClass.kt create mode 100644 integration-tests/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt create mode 100644 integration-tests/maven/projects/it-maven/src/main/kotlin/it/protected/ProtectedClass.kt diff --git a/docs/src/doc/docs/user_guide/cli/usage.md b/docs/src/doc/docs/user_guide/cli/usage.md index 65c4f93007..eca68c7d27 100644 --- a/docs/src/doc/docs/user_guide/cli/usage.md +++ b/docs/src/doc/docs/user_guide/cli/usage.md @@ -30,7 +30,7 @@ Dokka supports the following command line arguments: * `-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` - **Deprecated**, prefer using `documentedVisibilities`. Include protected and private code - * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL` (Kotlin-specific), `PACKAGE` (Java-specific package-private) + * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Overrides `includeNonPublic`. Default is `PUBLIC`. Possible values: `PUBLIC`, `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 diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md index 5f810cb79a..0b09b4303b 100644 --- a/docs/src/doc/docs/user_guide/gradle/usage.md +++ b/docs/src/doc/docs/user_guide/gradle/usage.md @@ -104,13 +104,14 @@ val dokkaHtml by getting(DokkaTask::class) { includeNonPublic.set(false) // A set of visibility modifiers that should be documented + // If set by user, overrides includeNonPublic. Default is PUBLIC documentedVisibilities.set( setOf( - Visibility.PUBLIC, // Same for both Kotlin and Java - 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 + DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier + DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility ) ) @@ -191,13 +192,16 @@ val dokkaHtml by getting(DokkaTask::class) { skipDeprecated.set(false) reportUndocumented.set(true) // Emit warnings about not documented members includeNonPublic.set(false) // Deprecated, prefer using documentedVisibilities - documentedVisibilities.set( // Visibilities that should be included in the documentation + + // Visibilities that should be included in the documentation + // If set by user, overrides includeNonPublic. Default is PUBLIC + documentedVisibilities.set( setOf( - Visibility.PUBLIC, // Same for both Kotlin and Java - 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 + DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java + DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier + DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility ) ) } diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md index cd8d890b56..d799396ab1 100644 --- a/docs/src/doc/docs/user_guide/maven/usage.md +++ b/docs/src/doc/docs/user_guide/maven/usage.md @@ -75,6 +75,7 @@ The available configuration options are shown below: + PUBLIC PRIVATE @@ -165,6 +166,7 @@ The available configuration options are shown below: false + PUBLIC PRIVATE diff --git a/integration-tests/cli/projects/it-cli/src/main/kotlin/it/basic/PublicClass.kt b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/basic/PublicClass.kt index 71bc7e6394..d7a7239278 100644 --- a/integration-tests/cli/projects/it-cli/src/main/kotlin/it/basic/PublicClass.kt +++ b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/basic/PublicClass.kt @@ -2,6 +2,9 @@ package it.basic +/** + * §PUBLIC§ (marker for asserts) + */ class PublicClass { /** * This function is public and documented @@ -24,6 +27,12 @@ class PublicClass { private fun privateUndocumentedFunction(): String = "" + /** + * This function is protected and documented + */ + protected fun protectedDocumentedFunction(): String = "" + + protected fun protectedUndocumentedFunction(): String = "" /** * This property is public and documented diff --git a/integration-tests/cli/projects/it-cli/src/main/kotlin/it/internal/InternalClass.kt b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/internal/InternalClass.kt new file mode 100644 index 0000000000..f5be5406eb --- /dev/null +++ b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/internal/InternalClass.kt @@ -0,0 +1,7 @@ +package it.internal + +/** + * §INTERNAL§ (marker for asserts) + * This class is internal and should not be rendered + */ +internal class InternalClass \ No newline at end of file diff --git a/integration-tests/cli/projects/it-cli/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt new file mode 100644 index 0000000000..230f5e0b81 --- /dev/null +++ b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt @@ -0,0 +1,12 @@ +package it.overriddenVisibility + +/** + * Private classes and methods generally should not be visible, but [documentedVisibilities] + * are overriden for this specific package to include private code + * + * §PRIVATE§ (marker for asserts) + */ +private class VisiblePrivateClass { + private val privateVal: Int = 0 + private fun privateMethod() {} +} \ No newline at end of file diff --git a/integration-tests/cli/projects/it-cli/src/main/kotlin/it/protected/ProtectedClass.kt b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/protected/ProtectedClass.kt new file mode 100644 index 0000000000..ad19f1a1a5 --- /dev/null +++ b/integration-tests/cli/projects/it-cli/src/main/kotlin/it/protected/ProtectedClass.kt @@ -0,0 +1,10 @@ +package it.protected + +/** + * Protected class should be visible because it's included in documentedVisibilities + * + * §PROTECTED§ (marker for asserts) + */ +protected class ProtectedClass { + protected fun protectedFun(): String = "protected" +} diff --git a/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt b/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt index 8935f8f531..b87badd71c 100644 --- a/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt +++ b/integration-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt @@ -84,6 +84,14 @@ class CliIntegrationTest : AbstractCliIntegrationTest() { assertNoEmptySpans(file) } + assertContentVisibility( + contentFiles = projectDir.allHtmlFiles().toList(), + documentPublic = true, + documentInternal = false, + documentProtected = false, + documentPrivate = false + ) + assertFalse( projectDir.resolve("output").resolve("index.html").readText().contains("emptypackagetest"), "Expected not to render empty packages" @@ -205,4 +213,50 @@ class CliIntegrationTest : AbstractCliIntegrationTest() { assertEquals(0, result.exitCode, "Expected exitCode 0 (Success)") assertFalse(result.output.contains("Loaded plugins: "), "Expected output to not contain info logs") } + + @Test + fun `custom documented visibility`() { + val dokkaOutputDir = File(projectDir, "output") + assertTrue(dokkaOutputDir.mkdirs()) + val process = ProcessBuilder( + "java", "-jar", cliJarFile.path, + "-outputDir", dokkaOutputDir.path, + "-pluginsClasspath", basePluginJarFile.path, + "-moduleName", "Basic Project", + "-sourceSet", + buildString { + append(" -sourceSetName cliMain") + append(" -src ${File(projectDir, "src").path}") + append(" -jdkVersion 8") + append(" -analysisPlatform jvm") + append(" -documentedVisibilities PUBLIC;PROTECTED") + append(" -perPackageOptions it.overriddenVisibility.*,+visibility:PRIVATE") + } + ) + .redirectErrorStream(true) + .start() + + val result = process.awaitProcessResult() + assertEquals(0, result.exitCode, "Expected exitCode 0 (Success)") + + val allHtmlFiles = projectDir.allHtmlFiles().toList() + + assertContentVisibility( + contentFiles = allHtmlFiles, + documentPublic = true, + documentProtected = true, // sourceSet documentedVisibilities + documentInternal = false, + documentPrivate = true // for overriddenVisibility package + ) + + assertContainsFilePaths( + outputFiles = allHtmlFiles, + expectedFilePaths = listOf( + // documentedVisibilities is overridden for package `overriddenVisibility` specifically + // to include private code, so html pages for it are expected to have been created + Regex("it\\.overriddenVisibility/-visible-private-class/private-method\\.html"), + Regex("it\\.overriddenVisibility/-visible-private-class/private-val\\.html"), + ) + ) + } } diff --git a/integration-tests/gradle/projects/it-basic/build.gradle.kts b/integration-tests/gradle/projects/it-basic/build.gradle.kts index e5abd7e1b0..c9302653ae 100644 --- a/integration-tests/gradle/projects/it-basic/build.gradle.kts +++ b/integration-tests/gradle/projects/it-basic/build.gradle.kts @@ -2,6 +2,7 @@ import org.jetbrains.dokka.gradle.DokkaTask import org.jetbrains.dokka.gradle.kotlinSourceSet import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.base.DokkaBaseConfiguration +import org.jetbrains.dokka.DokkaConfiguration import java.net.URL plugins { @@ -28,11 +29,20 @@ tasks.withType { moduleName.set("Basic Project") dokkaSourceSets { configureEach { + documentedVisibilities.set( + setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PROTECTED) + ) suppressedFiles.from(file("src/main/kotlin/it/suppressedByPath")) perPackageOption { matchingRegex.set("it.suppressedByPackage.*") suppress.set(true) } + perPackageOption { + matchingRegex.set("it.overriddenVisibility.*") + documentedVisibilities.set( + setOf(DokkaConfiguration.Visibility.PRIVATE) + ) + } sourceLink { localDirectory.set(file("src/main")) remoteUrl.set( diff --git a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt index fc4b36bd83..2958948cd4 100644 --- a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt +++ b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/basic/PublicClass.kt @@ -6,6 +6,8 @@ import RootPackageClass /** * This class, unlike [RootPackageClass] is located in a sub-package + * + * §PUBLIC§ (marker for asserts) */ class PublicClass { /** @@ -22,6 +24,13 @@ class PublicClass { internal fun internalUndocumentedFunction(): String = "" + /** + * This function is protected and documented + */ + protected fun protectedDocumentedFunction(): String = "" + + protected fun protectedUndocumentedFunction(): String = "" + /** * This function is private and documented */ @@ -44,6 +53,13 @@ class PublicClass { val internalUndocumentedProperty: Int = 0 + /** + * This property is protected and documented + */ + val protectedDocumentedProperty: Int = 0 + + val protectedUndocumentedProperty: Int = 0 + /** * This property private and documented */ diff --git a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/internal/InternalClass.kt b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/internal/InternalClass.kt index 7d42b978f7..6173d23919 100644 --- a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/internal/InternalClass.kt +++ b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/internal/InternalClass.kt @@ -1,7 +1,7 @@ package it.internal /** - * §INTERNAL§ + * §INTERNAL§ (marker for asserts) * This class is internal and should not be rendered */ internal class InternalClass diff --git a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt new file mode 100644 index 0000000000..230f5e0b81 --- /dev/null +++ b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt @@ -0,0 +1,12 @@ +package it.overriddenVisibility + +/** + * Private classes and methods generally should not be visible, but [documentedVisibilities] + * are overriden for this specific package to include private code + * + * §PRIVATE§ (marker for asserts) + */ +private class VisiblePrivateClass { + private val privateVal: Int = 0 + private fun privateMethod() {} +} \ No newline at end of file diff --git a/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/protected/ProtectedClass.kt b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/protected/ProtectedClass.kt new file mode 100644 index 0000000000..ad19f1a1a5 --- /dev/null +++ b/integration-tests/gradle/projects/it-basic/src/main/kotlin/it/protected/ProtectedClass.kt @@ -0,0 +1,10 @@ +package it.protected + +/** + * Protected class should be visible because it's included in documentedVisibilities + * + * §PROTECTED§ (marker for asserts) + */ +protected class ProtectedClass { + protected fun protectedFun(): String = "protected" +} diff --git a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt index cd13e47e8f..b7930f67c8 100644 --- a/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt +++ b/integration-tests/gradle/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt @@ -152,6 +152,8 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac ) } assertTrue(imagesDir.resolve("custom-resource.svg").isFile) + + assertConfiguredVisibility(this) } private fun File.assertJavadocOutputDir() { @@ -178,4 +180,26 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac private fun File.assertJekyllOutputDir() { assertTrue(isDirectory, "Missing dokka jekyll output directory") } + + private fun assertConfiguredVisibility(outputDir: File) { + val allHtmlFiles = outputDir.allHtmlFiles().toList() + + assertContentVisibility( + contentFiles = allHtmlFiles, + documentPublic = true, + documentProtected = true, // sourceSet documentedVisibilities + documentInternal = false, + documentPrivate = true // for overriddenVisibility package + ) + + assertContainsFilePaths( + outputFiles = allHtmlFiles, + expectedFilePaths = listOf( + // documentedVisibilities is overridden for package `overriddenVisibility` specifically + // to include private code, so html pages for it are expected to have been created + Regex("it\\.overriddenVisibility/-visible-private-class/private-method\\.html"), + Regex("it\\.overriddenVisibility/-visible-private-class/private-val\\.html"), + ) + ) + } } diff --git a/integration-tests/maven/projects/it-maven/pom.xml b/integration-tests/maven/projects/it-maven/pom.xml index cfc8ba6690..23f6548ffc 100644 --- a/integration-tests/maven/projects/it-maven/pom.xml +++ b/integration-tests/maven/projects/it-maven/pom.xml @@ -117,6 +117,10 @@ ${project.basedir}/src/main/java + + PUBLIC + PROTECTED + false @@ -138,6 +142,13 @@ true false + + + it.overriddenVisibility.* + + PRIVATE + + diff --git a/integration-tests/maven/projects/it-maven/src/main/kotlin/it/basic/PublicClass.kt b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/basic/PublicClass.kt index 71bc7e6394..d7a7239278 100644 --- a/integration-tests/maven/projects/it-maven/src/main/kotlin/it/basic/PublicClass.kt +++ b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/basic/PublicClass.kt @@ -2,6 +2,9 @@ package it.basic +/** + * §PUBLIC§ (marker for asserts) + */ class PublicClass { /** * This function is public and documented @@ -24,6 +27,12 @@ class PublicClass { private fun privateUndocumentedFunction(): String = "" + /** + * This function is protected and documented + */ + protected fun protectedDocumentedFunction(): String = "" + + protected fun protectedUndocumentedFunction(): String = "" /** * This property is public and documented diff --git a/integration-tests/maven/projects/it-maven/src/main/kotlin/it/internal/InternalClass.kt b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/internal/InternalClass.kt new file mode 100644 index 0000000000..6173d23919 --- /dev/null +++ b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/internal/InternalClass.kt @@ -0,0 +1,7 @@ +package it.internal + +/** + * §INTERNAL§ (marker for asserts) + * This class is internal and should not be rendered + */ +internal class InternalClass diff --git a/integration-tests/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt new file mode 100644 index 0000000000..230f5e0b81 --- /dev/null +++ b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt @@ -0,0 +1,12 @@ +package it.overriddenVisibility + +/** + * Private classes and methods generally should not be visible, but [documentedVisibilities] + * are overriden for this specific package to include private code + * + * §PRIVATE§ (marker for asserts) + */ +private class VisiblePrivateClass { + private val privateVal: Int = 0 + private fun privateMethod() {} +} \ No newline at end of file diff --git a/integration-tests/maven/projects/it-maven/src/main/kotlin/it/protected/ProtectedClass.kt b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/protected/ProtectedClass.kt new file mode 100644 index 0000000000..ad19f1a1a5 --- /dev/null +++ b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/protected/ProtectedClass.kt @@ -0,0 +1,10 @@ +package it.protected + +/** + * Protected class should be visible because it's included in documentedVisibilities + * + * §PROTECTED§ (marker for asserts) + */ +protected class ProtectedClass { + protected fun protectedFun(): String = "protected" +} diff --git a/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt b/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt index be70fdb469..0b532057eb 100644 --- a/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt +++ b/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt @@ -4,10 +4,7 @@ import org.jetbrains.dokka.it.AbstractIntegrationTest import org.jetbrains.dokka.it.awaitProcessResult import org.jetbrains.dokka.it.ProcessResult import java.io.File -import kotlin.test.BeforeTest -import kotlin.test.Test -import kotlin.test.assertEquals -import kotlin.test.assertTrue +import kotlin.test.* class MavenIntegrationTest : AbstractIntegrationTest() { @@ -69,6 +66,8 @@ class MavenIntegrationTest : AbstractIntegrationTest() { } assertEquals("""/* custom stylesheet */""", stylesDir.resolve("custom-style-to-add.css").readText()) assertTrue(imagesDir.resolve("custom-resource.svg").isFile) + + assertConfiguredVisibility(projectDir) } @Test @@ -146,4 +145,26 @@ class MavenIntegrationTest : AbstractIntegrationTest() { "Expected at least one report of undocumented java code (found $amountOfUndocumentedJavaReports)" ) } + + private fun assertConfiguredVisibility(projectDir: File) { + val projectHtmlFiles = projectDir.allHtmlFiles().toList() + + assertContentVisibility( + contentFiles = projectHtmlFiles, + documentPublic = true, + documentProtected = true, // sourceSet documentedVisibilities + documentInternal = false, + documentPrivate = true // for overriddenVisibility package + ) + + assertContainsFilePaths( + outputFiles = projectHtmlFiles, + expectedFilePaths = listOf( + // documentedVisibilities is overridden for package `overriddenVisibility` specifically + // to include private code, so html pages for it are expected to have been created + Regex("it\\.overriddenVisibility/-visible-private-class/private-method\\.html"), + Regex("it\\.overriddenVisibility/-visible-private-class/private-val\\.html"), + ) + ) + } } diff --git a/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt b/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt index a47adbc468..fcf6b9ddb5 100644 --- a/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt +++ b/integration-tests/src/main/kotlin/org/jetbrains/dokka/it/AbstractIntegrationTest.kt @@ -7,7 +7,9 @@ import org.junit.runner.RunWith import org.junit.runners.JUnit4 import java.io.File import java.net.URL +import kotlin.test.assertEquals import kotlin.test.assertFalse +import kotlin.test.assertNotNull import kotlin.test.assertTrue @RunWith(JUnit4::class) @@ -110,4 +112,57 @@ abstract class AbstractIntegrationTest { "Expected all templates to be substituted" ) } + + /** + * Asserts that [contentFiles] have no pages where content contains special visibility markers, + * such as §INTERNAL§ for `internal`, §PROTECTED§ for `protected` and §PRIVATE§ for `private` modifiers + * + * This can be used to check whether actual documented code corresponds to configured documented visibility + * + * @param contentFiles any readable content file such as html/md/rst/etc + */ + protected fun assertContentVisibility( + contentFiles: List, + documentPublic: Boolean, + documentProtected: Boolean, + documentInternal: Boolean, + documentPrivate: Boolean + ) { + val hasPublic = contentFiles.any { file -> "§PUBLIC§" in file.readText() } + assertEquals(documentPublic, hasPublic, "Expected content visibility and file content do not match for public") + + val hasInternal = contentFiles.any { file -> "§INTERNAL§" in file.readText() } + assertEquals( + documentInternal, + hasInternal, + "Expected content visibility and file content do not match for internal" + ) + + val hasProtected = contentFiles.any { file -> "§PROTECTED§" in file.readText() } + assertEquals( + documentProtected, + hasProtected, + "Expected content visibility and file content do not match for protected" + ) + + val hasPrivate = contentFiles.any { file -> "§PRIVATE§" in file.readText() } + assertEquals( + documentPrivate, + hasPrivate, + "Expected content visibility and file content do not match for private" + ) + } + + /** + * Check that [outputFiles] contain specific file paths provided in [expectedFilePaths]. + * Can be used for checking whether expected folders/pages have been created. + */ + protected fun assertContainsFilePaths(outputFiles: List, expectedFilePaths: List) { + expectedFilePaths.forEach { pathRegex -> + assertNotNull( + outputFiles.any { it.absolutePath.contains(pathRegex) }, + "Expected to find a file with path regex $pathRegex, but found nothing" + ) + } + } } From aaca2b4b101d66879ead6e693eb1e9ebafd6bb1c Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 16 Dec 2021 17:39:27 +0300 Subject: [PATCH 4/7] Fix maven plugin configuration overriding the default value --- runners/maven-plugin/src/main/kotlin/DokkaMojo.kt | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt index b73dd4060b..c6e8c60ab5 100644 --- a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt +++ b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt @@ -157,6 +157,9 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List = DokkaDefaults.documentedVisibilities + // hack to set the default value for lists, didn't find any other safe way + // maven seems to overwrite Kotlin's default initialization value, so it doesn't matter what you put there + get() = field.ifEmpty { DokkaDefaults.documentedVisibilities } @Parameter var failOnWarning: Boolean = DokkaDefaults.failOnWarning @@ -204,7 +207,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List Date: Fri, 17 Dec 2021 12:22:49 +0300 Subject: [PATCH 5/7] Remove test debug prints --- runners/maven-plugin/src/main/kotlin/DokkaMojo.kt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt index c6e8c60ab5..87c58edbed 100644 --- a/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt +++ b/runners/maven-plugin/src/main/kotlin/DokkaMojo.kt @@ -207,7 +207,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List Date: Fri, 17 Dec 2021 16:23:19 +0300 Subject: [PATCH 6/7] Correct an inconsistency with default values and leave a comment of intentions --- .../DocumentableVisibilityFilterTransformer.kt | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt index c15e2137c1..4b9da03bf7 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt @@ -40,12 +40,10 @@ class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMe 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 if (isDocumentedVisibilitiesOverridden) { - documentedVisibilities.contains(visibility) - } else { - visibility == DokkaConfiguration.Visibility.PUBLIC || includeNonPublic - } + return documentedVisibilities.contains(visibility) || (!isDocumentedVisibilitiesOverridden && includeNonPublic) } fun processModule(original: DModule) = From 0848a005866058611fa060af5cf1942b2a45610a Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 23 Dec 2021 12:16:36 +0300 Subject: [PATCH 7/7] Add a test for visibility of private setter --- .../kotlin/filter/VisibilityFilterTest.kt | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt index df45cde173..51ef4e83aa 100644 --- a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt @@ -339,6 +339,37 @@ class VisibilityFilterTest : BaseAbstractTest() { } } + @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 {