From bfd41ce2a0d43419a671961c19b7d755cffdcfc8 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 23 Dec 2021 14:32:18 +0300 Subject: Introduce documentedVisibilities setting (#2270) * Introduce `documentedVisibilities` setting * Remove hardcoded doc generation for Visibility.PUBLIC, correct tests * Add maven, gradle and cli integration tests for documentedVisibilities * Fix maven plugin configuration overriding the default value * Remove test debug prints * Correct an inconsistency with default values and leave a comment of intentions * Add a test for visibility of private setter --- 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 +- .../testRunner/TestDokkaConfigurationBuilder.kt | 4 + docs/src/doc/docs/user_guide/cli/usage.md | 6 +- docs/src/doc/docs/user_guide/gradle/usage.md | 34 +- docs/src/doc/docs/user_guide/maven/usage.md | 23 ++ .../it-cli/src/main/kotlin/it/basic/PublicClass.kt | 9 + .../src/main/kotlin/it/internal/InternalClass.kt | 7 + .../it/overriddenVisibility/VisiblePrivateClass.kt | 12 + .../src/main/kotlin/it/protected/ProtectedClass.kt | 10 + .../jetbrains/dokka/it/cli/CliIntegrationTest.kt | 54 +++ .../gradle/projects/it-basic/build.gradle.kts | 10 + .../src/main/kotlin/it/basic/PublicClass.kt | 16 + .../src/main/kotlin/it/internal/InternalClass.kt | 2 +- .../it/overriddenVisibility/VisiblePrivateClass.kt | 12 + .../src/main/kotlin/it/protected/ProtectedClass.kt | 10 + .../dokka/it/gradle/BasicGradleIntegrationTest.kt | 24 ++ integration-tests/maven/projects/it-maven/pom.xml | 11 + .../src/main/kotlin/it/basic/PublicClass.kt | 9 + .../src/main/kotlin/it/internal/InternalClass.kt | 7 + .../it/overriddenVisibility/VisiblePrivateClass.kt | 12 + .../src/main/kotlin/it/protected/ProtectedClass.kt | 10 + .../dokka/it/maven/MavenIntegrationTest.kt | 29 +- .../jetbrains/dokka/it/AbstractIntegrationTest.kt | 55 +++ .../DocumentableVisibilityFilterTransformer.kt | 28 +- .../content/signatures/ContentForSignaturesTest.kt | 8 +- .../test/kotlin/filter/DeprecationFilterTest.kt | 8 +- .../test/kotlin/filter/JavaVisibilityFilterTest.kt | 195 ++++++++- .../src/test/kotlin/filter/VisibilityFilterTest.kt | 442 ++++++++++++++++++++- plugins/base/src/test/kotlin/model/JavaTest.kt | 8 +- .../ReportUndocumentedTransformerTest.kt | 6 +- ...nfigurationDocumentableFilterTransformerTest.kt | 2 + ...efaultDescriptorToDocumentableTranslatorTest.kt | 12 +- runners/cli/api/cli.api | 7 + runners/cli/src/main/kotlin/cli/main.kt | 14 + .../dokka/gradle/GradleDokkaSourceSetBuilder.kt | 4 + .../dokka/gradle/GradlePackageOptionsBuilder.kt | 8 + .../jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt | 1 + .../dokka/gradle/DokkaConfigurationJsonTest.kt | 1 + .../gradle/DokkaConfigurationSerializableTest.kt | 1 + .../gradle/GradleDokkaSourceSetBuilderTest.kt | 17 + runners/maven-plugin/api/maven-plugin.api | 4 + runners/maven-plugin/src/main/kotlin/DokkaMojo.kt | 11 + 46 files changed, 1185 insertions(+), 45 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/core/api/core.api b/core/api/core.api index 46a4c3a5..471f6314 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 67dee9ae..75c4c0af 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 56fe8437..46b338d2 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(DokkaConfiguration.Visibility.PUBLIC) 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 743cc6c2..4d23ce68 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 b1f6a381..83335672 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 33f45b02..804e02ce 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 = DokkaDefaults.documentedVisibilities, 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 = 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 9bfcb6fb..eca68c7d 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. 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 - * `-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 cc36329d..0b09b430 100644 --- a/docs/src/doc/docs/user_guide/gradle/usage.md +++ b/docs/src/doc/docs/user_guide/gradle/usage.md @@ -100,9 +100,21 @@ 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 + // If set by user, overrides includeNonPublic. Default is PUBLIC + documentedVisibilities.set( + setOf( + 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 + ) + ) + // Do not output deprecated members. Applies globally, can be overridden by packageOptions skipDeprecated.set(false) @@ -173,11 +185,25 @@ 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 + + // Visibilities that should be included in the documentation + // If set by user, overrides includeNonPublic. Default is PUBLIC + documentedVisibilities.set( + setOf( + 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 + ) + ) } // 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 25ccabf0..d799396a 100644 --- a/docs/src/doc/docs/user_guide/maven/usage.md +++ b/docs/src/doc/docs/user_guide/maven/usage.md @@ -73,6 +73,16 @@ The available configuration options are shown below: packages.md extra.md + + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + @@ -148,9 +158,22 @@ The available configuration options are shown below: false + true + + false + + + + + PUBLIC + PRIVATE + PROTECTED + INTERNAL + PACKAGE + 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 71bc7e63..d7a72392 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 00000000..f5be5406 --- /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 00000000..230f5e0b --- /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 00000000..ad19f1a1 --- /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 8935f8f5..b87badd7 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 e5abd7e1..c9302653 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 fc4b36bd..2958948c 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 7d42b978..6173d239 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 00000000..230f5e0b --- /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 00000000..ad19f1a1 --- /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 cd13e47e..b7930f67 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 cfc8ba66..23f6548f 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 71bc7e63..d7a72392 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 00000000..6173d239 --- /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 00000000..230f5e0b --- /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 00000000..ad19f1a1 --- /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 be70fdb4..0b532057 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 a47adbc4..fcf6b9dd 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" + ) + } + } } diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt index bd39b040..4b9da03b 100644 --- a/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt +++ b/plugins/base/src/main/kotlin/transformers/documentables/DocumentableVisibilityFilterTransformer.kt @@ -5,6 +5,7 @@ import org.jetbrains.dokka.model.* import org.jetbrains.dokka.plugability.DokkaContext import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet +import org.jetbrains.dokka.DokkaDefaults class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMergeDocumentableTransformer { @@ -20,10 +21,29 @@ class DocumentableVisibilityFilterTransformer(val context: DokkaContext) : PreMe ) { fun Visibility.isAllowedInPackage(packageName: String?) = when (this) { is JavaVisibility.Public, - is KotlinVisibility.Public -> true - else -> packageName != null - && packageOptions.firstOrNull { Regex(it.matchingRegex).matches(packageName) }?.includeNonPublic - ?: globalOptions.includeNonPublic + is KotlinVisibility.Public -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PUBLIC) + is JavaVisibility.Private, + is KotlinVisibility.Private -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PRIVATE) + is JavaVisibility.Protected, + is KotlinVisibility.Protected -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PROTECTED) + is KotlinVisibility.Internal -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.INTERNAL) + is JavaVisibility.Default -> isAllowedInPackage(packageName, DokkaConfiguration.Visibility.PACKAGE) + } + + private fun isAllowedInPackage(packageName: String?, visibility: DokkaConfiguration.Visibility): Boolean { + val packageOpts = packageName.takeIf { it != null }?.let { name -> + packageOptions.firstOrNull { Regex(it.matchingRegex).matches(name) } + } + + val (documentedVisibilities, includeNonPublic) = when { + packageOpts != null -> packageOpts.documentedVisibilities to packageOpts.includeNonPublic + else -> globalOptions.documentedVisibilities to globalOptions.includeNonPublic + } + + // if `documentedVisibilities` is explicitly overridden by the user (i.e. not default value by reference), + // deprecated `includeNonPublic` should not be taken into account, so that only one setting prevails + val isDocumentedVisibilitiesOverridden = documentedVisibilities !== DokkaDefaults.documentedVisibilities + return documentedVisibilities.contains(visibility) || (!isDocumentedVisibilitiesOverridden && includeNonPublic) } fun processModule(original: DModule) = diff --git a/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt b/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt index e7c35a66..c0f1ebfb 100644 --- a/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt +++ b/plugins/base/src/test/kotlin/content/signatures/ContentForSignaturesTest.kt @@ -1,6 +1,7 @@ package content.signatures import matchers.content.* +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.model.doc.Text import org.jetbrains.dokka.pages.* @@ -18,7 +19,12 @@ class ContentForSignaturesTest : BaseAbstractTest() { sourceSet { sourceRoots = listOf("src/") analysisPlatform = "jvm" - includeNonPublic = true + documentedVisibilities = setOf( + DokkaConfiguration.Visibility.PUBLIC, + DokkaConfiguration.Visibility.PRIVATE, + DokkaConfiguration.Visibility.PROTECTED, + DokkaConfiguration.Visibility.INTERNAL, + ) } } } diff --git a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt index 4431d383..e6f2c5e9 100644 --- a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt @@ -1,5 +1,6 @@ package filter +import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest import org.junit.jupiter.api.Assertions @@ -109,7 +110,8 @@ class DeprecationFilterTest : BaseAbstractTest() { true, false, true, - false + false, + DokkaDefaults.documentedVisibilities ) ) } @@ -147,7 +149,9 @@ class DeprecationFilterTest : BaseAbstractTest() { false, false, false, - false) + false, + DokkaDefaults.documentedVisibilities + ) ) } } diff --git a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt index 32c00e92..e6acec92 100644 --- a/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt +++ b/plugins/base/src/test/kotlin/filter/JavaVisibilityFilterTest.kt @@ -1,17 +1,204 @@ package filter +import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.DokkaConfigurationImpl +import org.jetbrains.dokka.DokkaDefaults import org.jetbrains.dokka.PackageOptionsImpl import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest +import org.jetbrains.dokka.model.DClass +import org.jetbrains.dokka.model.DModule +import org.junit.jupiter.api.Test import org.junit.jupiter.params.ParameterizedTest import org.junit.jupiter.params.provider.MethodSource import testApi.testRunner.dokkaConfiguration import kotlin.test.assertEquals class JavaVisibilityFilterTest : BaseAbstractTest() { + + @Test + fun `should document nothing private if no visibilities are included`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | private String privateProperty = "privateProperty"; + | + | public void publicFunction() { } + | private void privateFunction() { } + | } + """.trimIndent(), + includedVisibility = DokkaDefaults.documentedVisibilities + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(1, it.size) + assertEquals("publicProperty", it[0].name) + } + clazz.functions.also { + assertEquals(1, it.size) + assertEquals("publicFunction", it[0].name) + } + } + } + + @Test + fun `should document private within public class`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | protected String noise = "noise"; + | + | private String privateProperty = "privateProperty"; + | + | public void publicFunction() { } + | private void privateFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PRIVATE) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("privateProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFunction", it[0].name) + assertEquals("privateFunction", it[1].name) + } + } + } + + @Test + fun `should document package private within private class`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | protected String noise = "noise"; + | + | String packagePrivateProperty = "packagePrivateProperty"; + | + | public void publicFunction() { } + | void packagePrivateFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PACKAGE) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("packagePrivateProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFunction", it[0].name) + assertEquals("packagePrivateFunction", it[1].name) + } + } + } + + @Test + fun `should document protected within public class`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | String noise = "noise"; + | + | protected String protectedProperty = "protectedProperty"; + | + | public void publicFunction() { } + | protected void protectedFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf(DokkaConfiguration.Visibility.PUBLIC, DokkaConfiguration.Visibility.PROTECTED) + ) { module -> + val clazz = module.first().packages.first().classlikes.filterIsInstance().first() + clazz.properties.also { + assertEquals(2, it.size) + assertEquals("publicProperty", it[0].name) + assertEquals("protectedProperty", it[1].name) + } + clazz.functions.also { + assertEquals(2, it.size) + assertEquals("publicFunction", it[0].name) + assertEquals("protectedFunction", it[1].name) + } + } + } + + @Test + fun `should include all visibilities`() { + testVisibility( + """ + | public class JavaVisibilityTest { + | public String publicProperty = "publicProperty"; + | private String privateProperty = "privateProperty"; + | String packagePrivateProperty = "packagePrivateProperty"; + | protected String protectedProperty = "protectedProperty"; + | + | public void publicFunction() { } + | private void privateFunction() { } + | void packagePrivateFunction() { } + | protected void protectedFunction() { } + | } + """.trimIndent(), + includedVisibility = setOf( + DokkaConfiguration.Visibility.PUBLIC, + DokkaConfiguration.Visibility.PRIVATE, + DokkaConfiguration.Visibility.PROTECTED