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 --- 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 ++++++++ .../org/jetbrains/dokka/gradle/toDokkaSourceSetImpl.kt | 1 + .../dokka/gradle/DokkaConfigurationJsonTest.kt | 1 + .../dokka/gradle/DokkaConfigurationSerializableTest.kt | 1 + .../dokka/gradle/GradleDokkaSourceSetBuilderTest.kt | 17 +++++++++++++++++ runners/maven-plugin/api/maven-plugin.api | 4 ++++ runners/maven-plugin/src/main/kotlin/DokkaMojo.kt | 11 +++++++++++ 10 files changed, 68 insertions(+) (limited to 'runners') diff --git a/runners/cli/api/cli.api b/runners/cli/api/cli.api index b7ea94ff..e1e52c05 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 7a7a5582..739539a9 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,8 @@ 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() + .ifEmpty { DokkaDefaults.documentedVisibilities } } } @@ -305,6 +312,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 de8eed77..abaa2536 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 9b6108b8..f15a6462 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 74e3d16d..56c3f071 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 68506876..877d3b37 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 2887f957..811f7736 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 6216b5d7..949e4949 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 c45e3259..3b4ace56 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 58039ab9..87c58edb 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,12 @@ 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 @@ -198,6 +207,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List