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

10 files changed, 68 insertions, 0 deletions

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 <init> ([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<String>): 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<String>): DokkaConfig
         override val noStdlibLink = noStdlibLink
         override val noJdkLink = noJdkLink
         override val suppressedFiles = suppressedFiles.toMutableSet()
+        override val documentedVisibilities: Set<DokkaConfiguration.Visibility> = documentedVisibilities.toSet()
+            .ifEmpty { DokkaDefaults.documentedVisibilities }
     }
 }
 
@@ -305,6 +312,13 @@ object ArgTypePlatform : ArgType<Platform>(true) {
         get() = "{ String that represents platform }"
 }
 
+object ArgTypeVisibility : ArgType<DokkaConfiguration.Visibility>(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<DokkaConfiguration.PluginConfiguration>(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
@@ -60,6 +60,10 @@ open class GradleDokkaSourceSetBuilder(
         .safeConvention(DokkaDefaults.includeNonPublic)
 
     @Input
+    val documentedVisibilities: SetProperty<DokkaConfiguration.Visibility> = project.objects.setProperty<DokkaConfiguration.Visibility>()
+        .convention(DokkaDefaults.documentedVisibilities)
+
+    @Input
     val reportUndocumented: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .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
@@ -23,6 +26,10 @@ class GradlePackageOptionsBuilder(
         .safeConvention(DokkaDefaults.includeNonPublic)
 
     @Input
+    val documentedVisibilities: SetProperty<DokkaConfiguration.Visibility> = project.objects.setProperty<DokkaConfiguration.Visibility>()
+        .convention(DokkaDefaults.documentedVisibilities)
+
+    @Input
     val reportUndocumented: Property<Boolean> = project.objects.safeProperty<Boolean>()
         .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
@@ -163,6 +163,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)
         assertEquals(
@@ -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 <init> ()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<Dependenc
 
         @Parameter
         override var suppress: Boolean = DokkaDefaults.suppress
+
+        @Parameter(property = "visibility")
+        override var documentedVisibilities: Set<DokkaConfiguration.Visibility> = DokkaDefaults.documentedVisibilities
     }
 
     @Parameter
@@ -152,6 +155,12 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependenc
     @Parameter
     var includeNonPublic: Boolean = DokkaDefaults.includeNonPublic
 
+    @Parameter(property = "visibility")
+    var documentedVisibilities: Set<DokkaConfiguration.Visibility> = 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<Dependenc
             samples = samples.map(::File).toSet(),
             includes = includes.map(::File).toSet(),
             includeNonPublic = includeNonPublic,
+            documentedVisibilities = documentedVisibilities,
             reportUndocumented = reportUndocumented,
             skipEmptyPackages = skipEmptyPackages,
             skipDeprecated = skipDeprecated,
@@ -207,6 +217,7 @@ abstract class AbstractDokkaMojo(private val defaultDokkaPlugins: List<Dependenc
                 PackageOptionsImpl(
                     matchingRegex = it.matchingRegex,
                     includeNonPublic = it.includeNonPublic,
+                    documentedVisibilities = it.documentedVisibilities,
                     reportUndocumented = it.reportUndocumented,
                     skipDeprecated = it.skipDeprecated,
                     suppress = it.suppress