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

6 files changed, 73 insertions, 1 deletions

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<DokkaTask> {
     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 {
     /**
@@ -23,6 +25,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
      */
     private fun privateDocumentedFunction(): String = ""
@@ -45,6 +54,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
      */
     private val privateDocumentedProperty: Int = 0
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"),
+            )
+        )
+    }
 }