From bfd41ce2a0d43419a671961c19b7d755cffdcfc8 Mon Sep 17 00:00:00 2001
From: Ignat Beresnev <ignat@beresnev.me>
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/src/main/kotlin/DokkaBootstrapImpl.kt   |  7 ++++++
 core/src/main/kotlin/configuration.kt        | 36 ++++++++++++++++++++++++++++
 core/src/main/kotlin/defaultConfiguration.kt |  2 ++
 3 files changed, 45 insertions(+)

(limited to 'core/src')

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<String>): List<PackageOptions> = 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<DokkaConfiguration.Visibility> = 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<DokkaSourceSetID>
         val samples: Set<File>
         val includes: Set<File>
+        @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<File>
         val analysisPlatform: Platform
+        val documentedVisibilities: Set<Visibility>
+    }
+
+    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<Visibility>
     }
 
     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<File> = emptySet(),
     override val analysisPlatform: Platform = DokkaDefaults.analysisPlatform,
+    override val documentedVisibilities: Set<DokkaConfiguration.Visibility> = 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.Visibility>,
 ) : DokkaConfiguration.PackageOptions
 
 
-- 
cgit