Skip to content

Commit

Permalink
Add maven, gradle and cli integration tests for documentedVisibilities
Browse files Browse the repository at this point in the history
  • Loading branch information
IgnatBeresnev committed Dec 16, 2021
1 parent 398fe2d commit fc47d3e
Show file tree
Hide file tree
Showing 21 changed files with 312 additions and 17 deletions.
2 changes: 1 addition & 1 deletion docs/src/doc/docs/user_guide/cli/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
26 changes: 15 additions & 11 deletions docs/src/doc/docs/user_guide/gradle/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
)
)

Expand Down Expand Up @@ -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
)
)
}
Expand Down
2 changes: 2 additions & 0 deletions docs/src/doc/docs/user_guide/maven/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down Expand Up @@ -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 -->
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

package it.basic

/**
* §PUBLIC§ (marker for asserts)
*/
class PublicClass {
/**
* This function is public and documented
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
package it.internal

/**
* §INTERNAL§ (marker for asserts)
* This class is internal and should not be rendered
*/
internal class InternalClass
Original file line number Diff line number Diff line change
@@ -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() {}
}
Original file line number Diff line number Diff line change
@@ -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"
}
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down Expand Up @@ -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"),
)
)
}
}
10 changes: 10 additions & 0 deletions integration-tests/gradle/projects/it-basic/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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(
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ import RootPackageClass

/**
* This class, unlike [RootPackageClass] is located in a sub-package
*
* §PUBLIC§ (marker for asserts)
*/
class PublicClass {
/**
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
package it.internal

/**
* §INTERNAL§
* §INTERNAL§ (marker for asserts)
* This class is internal and should not be rendered
*/
internal class InternalClass
Original file line number Diff line number Diff line change
@@ -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() {}
}
Original file line number Diff line number Diff line change
@@ -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"
}
Original file line number Diff line number Diff line change
Expand Up @@ -152,6 +152,8 @@ class BasicGradleIntegrationTest(override val versions: BuildVersions) : Abstrac
)
}
assertTrue(imagesDir.resolve("custom-resource.svg").isFile)

assertConfiguredVisibility(this)
}

private fun File.assertJavadocOutputDir() {
Expand All @@ -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"),
)
)
}
}
11 changes: 11 additions & 0 deletions integration-tests/maven/projects/it-maven/pom.xml
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,9 @@

package it.basic

/**
* §PUBLIC§ (marker for asserts)
*/
class PublicClass {
/**
* This function is public and documented
Expand All @@ -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
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
package it.internal

/**
* §INTERNAL§ (marker for asserts)
* This class is internal and should not be rendered
*/
internal class InternalClass
Original file line number Diff line number Diff line change
@@ -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() {}
}
Loading

0 comments on commit fc47d3e

Please sign in to comment.