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

5 files changed, 92 insertions, 0 deletions

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"),
+            )
+        )
+    }
 }