Add maven, gradle and cli integration tests for documentedVisibilities

Kotlin · Dec 16, 2021 · e85c976 · e85c976
1 parent 03bd473
commit e85c976
Show file tree

Hide file tree

Showing 21 changed files with 312 additions and 17 deletions.
diff --git a/docs/src/doc/docs/user_guide/cli/usage.md b/docs/src/doc/docs/user_guide/cli/usage.md
@@ -30,7 +30,7 @@ Dokka supports the following command line arguments:
     * `-samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag) separated by `;`
     * `-includes` - list of files containing the documentation for the module and individual packages separated by `;`
     * `-includeNonPublic` - **Deprecated**, prefer using `documentedVisibilities`. Include protected and private code
-    * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL` (Kotlin-specific), `PACKAGE` (Java-specific package-private)
+    * `-documentedVisibilities` - a list of visibility modifiers (separated by `;`) that should be documented. Overrides `includeNonPublic`. Default is `PUBLIC`. Possible values: `PUBLIC`, `PRIVATE`, `PROTECTED`, `INTERNAL` (Kotlin-specific), `PACKAGE` (Java-specific package-private)
     * `-skipDeprecated` - if set, deprecated elements are not included in the generated documentation
     * `-reportUndocumented` - warn about undocumented members
     * `-noSkipEmptyPackages` - create index pages for empty packages

diff --git a/docs/src/doc/docs/user_guide/gradle/usage.md b/docs/src/doc/docs/user_guide/gradle/usage.md
@@ -104,13 +104,14 @@ val dokkaHtml by getting(DokkaTask::class) {
             includeNonPublic.set(false)
 
             // A set of visibility modifiers that should be documented
+            // If set by user, overrides includeNonPublic. Default is PUBLIC
             documentedVisibilities.set(
                 setOf(
-                    Visibility.PUBLIC, // Same for both Kotlin and Java
-                    Visibility.PRIVATE, // Same for both Kotlin and Java
-                    Visibility.PROTECTED, // Same for both Kotlin and Java
-                    Visibility.INTERNAL, // Kotlin-specific internal modifier
-                    Visibility.PACKAGE, // Java-specific package-private visibility
+                    DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java
+                    DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier
+                    DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility
                 )
             )
 
@@ -191,13 +192,16 @@ val dokkaHtml by getting(DokkaTask::class) {
                 skipDeprecated.set(false)
                 reportUndocumented.set(true) // Emit warnings about not documented members 
                 includeNonPublic.set(false) // Deprecated, prefer using documentedVisibilities
-                documentedVisibilities.set( // Visibilities that should be included in the documentation
+
+                // Visibilities that should be included in the documentation
+                // If set by user, overrides includeNonPublic. Default is PUBLIC
+                documentedVisibilities.set(
                     setOf(
-                        Visibility.PUBLIC, // Same for both Kotlin and Java
-                        Visibility.PRIVATE, // Same for both Kotlin and Java
-                        Visibility.PROTECTED, // Same for both Kotlin and Java
-                        Visibility.INTERNAL, // Kotlin-specific internal modifier
-                        Visibility.PACKAGE, // Java-specific package-private visibility
+                        DokkaConfiguration.Visibility.PUBLIC, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.PRIVATE, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.PROTECTED, // Same for both Kotlin and Java
+                        DokkaConfiguration.Visibility.INTERNAL, // Kotlin-specific internal modifier
+                        DokkaConfiguration.Visibility.PACKAGE, // Java-specific package-private visibility
                     )
                 )
             }

diff --git a/docs/src/doc/docs/user_guide/maven/usage.md b/docs/src/doc/docs/user_guide/maven/usage.md
@@ -75,6 +75,7 @@ The available configuration options are shown below:
         </includes>
 
         <!-- A list of visibility modifiers that should be documented -->
+        <!-- If set by user, overrides includeNonPublic. Default is PUBLIC -->
         <documentedVisibilities>
             <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java -->
             <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java -->
@@ -165,6 +166,7 @@ The available configuration options are shown below:
                 <includeNonPublic>false</includeNonPublic>
 
                 <!-- A list of visibility modifiers that should be documented -->
+                <!-- If set by user, overrides includeNonPublic. Default is PUBLIC -->
                 <documentedVisibilities>
                     <visibility>PUBLIC</visibility> <!-- Same for both kotlin and java -->
                     <visibility>PRIVATE</visibility> <!-- Same for both kotlin and java -->

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
@@ -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
@@ -0,0 +1,7 @@
+package it.internal
+
+/**
+ * §INTERNAL§ (marker for asserts)
+ * This class is internal and should not be rendered
+ */
+internal class InternalClass
diff --git a/...-tests/cli/projects/it-cli/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt b/...-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() {}
+}
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
@@ -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/...ion-tests/cli/src/integrationTest/kotlin/org/jetbrains/dokka/it/cli/CliIntegrationTest.kt b/...ion-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"),
+            )
+        )
+    }
 }
diff --git 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
@@ -6,6 +6,8 @@ import RootPackageClass
 
 /**
  * This class, unlike [RootPackageClass] is located in a sub-package
+ *
+ * §PUBLIC§ (marker for asserts)
  */
 class PublicClass {
     /**
@@ -22,6 +24,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
      */
@@ -44,6 +53,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
      */

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
@@ -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/...s/gradle/projects/it-basic/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt b/...s/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() {}
+}
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
@@ -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/...le/src/integrationTest/kotlin/org/jetbrains/dokka/it/gradle/BasicGradleIntegrationTest.kt b/...le/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"),
+            )
+        )
+    }
 }
diff --git a/integration-tests/maven/projects/it-maven/pom.xml b/integration-tests/maven/projects/it-maven/pom.xml
@@ -117,6 +117,10 @@
                         <dir>${project.basedir}/src/main/java</dir>
                     </sourceDirectories>
 
+                    <documentedVisibilities>
+                        <visibility>PUBLIC</visibility>
+                        <visibility>PROTECTED</visibility>
+                    </documentedVisibilities>
 
                     <!-- Disable linking to online kotlin-stdlib documentation  -->
                     <noStdlibLink>false</noStdlibLink>
@@ -138,6 +142,13 @@
                             <reportUndocumented>true</reportUndocumented>
                             <includeNonPublic>false</includeNonPublic>
                         </packageOptions>
+
+                        <packageOptions>
+                            <matchingRegex>it.overriddenVisibility.*</matchingRegex>
+                            <documentedVisibilities>
+                                <visibility>PRIVATE</visibility>
+                            </documentedVisibilities>
+                        </packageOptions>
                     </perPackageOptions>
                     <pluginsConfiguration>
                         <org.jetbrains.dokka.base.DokkaBase>

diff --git a/integration-tests/maven/projects/it-maven/src/main/kotlin/it/basic/PublicClass.kt b/integration-tests/maven/projects/it-maven/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/maven/projects/it-maven/src/main/kotlin/it/internal/InternalClass.kt b/integration-tests/maven/projects/it-maven/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
diff --git a/...ts/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt b/...ts/maven/projects/it-maven/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() {}
+}