From bfd41ce2a0d43419a671961c19b7d755cffdcfc8 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev 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 --- integration-tests/maven/projects/it-maven/pom.xml | 11 ++++++++ .../src/main/kotlin/it/basic/PublicClass.kt | 9 +++++++ .../src/main/kotlin/it/internal/InternalClass.kt | 7 ++++++ .../it/overriddenVisibility/VisiblePrivateClass.kt | 12 +++++++++ .../src/main/kotlin/it/protected/ProtectedClass.kt | 10 ++++++++ .../dokka/it/maven/MavenIntegrationTest.kt | 29 +++++++++++++++++++--- 6 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 integration-tests/maven/projects/it-maven/src/main/kotlin/it/internal/InternalClass.kt create mode 100644 integration-tests/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt create mode 100644 integration-tests/maven/projects/it-maven/src/main/kotlin/it/protected/ProtectedClass.kt (limited to 'integration-tests/maven') diff --git a/integration-tests/maven/projects/it-maven/pom.xml b/integration-tests/maven/projects/it-maven/pom.xml index cfc8ba66..23f6548f 100644 --- a/integration-tests/maven/projects/it-maven/pom.xml +++ b/integration-tests/maven/projects/it-maven/pom.xml @@ -117,6 +117,10 @@ ${project.basedir}/src/main/java + + PUBLIC + PROTECTED + false @@ -138,6 +142,13 @@ true false + + + it.overriddenVisibility.* + + PRIVATE + + 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 index 71bc7e63..d7a72392 100644 --- 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 new file mode 100644 index 00000000..6173d239 --- /dev/null +++ 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/integration-tests/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/overriddenVisibility/VisiblePrivateClass.kt new file mode 100644 index 00000000..230f5e0b --- /dev/null +++ b/integration-tests/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() {} +} \ No newline at end of file diff --git a/integration-tests/maven/projects/it-maven/src/main/kotlin/it/protected/ProtectedClass.kt b/integration-tests/maven/projects/it-maven/src/main/kotlin/it/protected/ProtectedClass.kt new file mode 100644 index 00000000..ad19f1a1 --- /dev/null +++ b/integration-tests/maven/projects/it-maven/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/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt b/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt index be70fdb4..0b532057 100644 --- a/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt +++ b/integration-tests/maven/src/integrationTest/kotlin/org/jetbrains/dokka/it/maven/MavenIntegrationTest.kt @@ -4,10 +4,7 @@ import org.jetbrains.dokka.it.AbstractIntegrationTest import org.jetbrains.dokka.it.awaitProcessResult import org.jetbrains.dokka.it.ProcessResult import java.io.File -import kotlin.test.BeforeTest -import kotlin.test.Test -import kotlin.test.assertEquals -import kotlin.test.assertTrue +import kotlin.test.* class MavenIntegrationTest : AbstractIntegrationTest() { @@ -69,6 +66,8 @@ class MavenIntegrationTest : AbstractIntegrationTest() { } assertEquals("""/* custom stylesheet */""", stylesDir.resolve("custom-style-to-add.css").readText()) assertTrue(imagesDir.resolve("custom-resource.svg").isFile) + + assertConfiguredVisibility(projectDir) } @Test @@ -146,4 +145,26 @@ class MavenIntegrationTest : AbstractIntegrationTest() { "Expected at least one report of undocumented java code (found $amountOfUndocumentedJavaReports)" ) } + + private fun assertConfiguredVisibility(projectDir: File) { + val projectHtmlFiles = projectDir.allHtmlFiles().toList() + + assertContentVisibility( + contentFiles = projectHtmlFiles, + documentPublic = true, + documentProtected = true, // sourceSet documentedVisibilities + documentInternal = false, + documentPrivate = true // for overriddenVisibility package + ) + + assertContainsFilePaths( + outputFiles = projectHtmlFiles, + 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"), + ) + ) + } } -- cgit