Empty modules filtering (#1699)

9 files changed, 62 insertions, 35 deletions

diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt
index ac070ab4..938c7701 100644
--- a/plugins/base/src/main/kotlin/DokkaBase.kt
+++ b/plugins/base/src/main/kotlin/DokkaBase.kt
@@ -80,6 +80,12 @@ class DokkaBase : DokkaPlugin() {
         }
     }
 
+    val emptyModulesFilter by extending {
+        preMergeDocumentableTransformer with EmptyModulesFilterTransformer() order {
+            after(emptyPackagesFilter)
+        }
+    }
+
     val modulesAndPackagesDocumentation by extending {
         preMergeDocumentableTransformer providing ::ModuleAndPackageDocumentationTransformer
     }
diff --git a/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt b/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt
index 1689a1dd..9bf61af9 100644
--- a/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt
+++ b/plugins/base/src/main/kotlin/generation/SingleModuleGeneration.kt
@@ -1,4 +1,3 @@
-
 package org.jetbrains.dokka.base.generation
 
 import kotlinx.coroutines.Dispatchers
@@ -32,6 +31,7 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
 
         report("Merging documentation models")
         val documentationModel = mergeDocumentationModels(transformedDocumentationBeforeMerge)
+            ?: exitGenerationGracefully("Nothing to document")
 
         report("Transforming documentation model after merging")
         val transformedDocumentation = transformDocumentationModelAfterMerge(documentationModel)
@@ -56,7 +56,8 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
     }
 
     fun transformDocumentationModelBeforeMerge(modulesFromPlatforms: List<DModule>) =
-        context.plugin<DokkaBase>().query { preMergeDocumentableTransformer }.fold(modulesFromPlatforms) { acc, t -> t(acc) }
+        context.plugin<DokkaBase>().query { preMergeDocumentableTransformer }
+            .fold(modulesFromPlatforms) { acc, t -> t(acc) }
 
     fun mergeDocumentationModels(modulesFromPlatforms: List<DModule>) =
         context.single(CoreExtensions.documentableMerger).invoke(modulesFromPlatforms)
@@ -99,7 +100,7 @@ class SingleModuleGeneration(private val context: DokkaContext) : Generation {
 
     private suspend fun translateSources(sourceSet: DokkaConfiguration.DokkaSourceSet, context: DokkaContext) =
         context[CoreExtensions.sourceToDocumentableTranslator].parallelMap { translator ->
-            when(translator){
+            when (translator) {
                 is AsyncSourceToDocumentableTranslator -> translator.invokeSuspending(sourceSet, context)
                 else -> translator.invoke(sourceSet, context)
             }
diff --git a/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt b/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt
index d76ba597..2694adc9 100644
--- a/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt
+++ b/plugins/base/src/main/kotlin/renderers/DefaultRenderer.kt
@@ -7,7 +7,6 @@ import kotlinx.coroutines.runBlocking
 import org.jetbrains.dokka.DokkaException
 import org.jetbrains.dokka.base.DokkaBase
 import org.jetbrains.dokka.base.resolvers.local.LocationProvider
-import org.jetbrains.dokka.base.resolvers.local.resolveOrThrow
 import org.jetbrains.dokka.model.DisplaySourceSet
 import org.jetbrains.dokka.pages.*
 import org.jetbrains.dokka.plugability.DokkaContext
@@ -169,12 +168,20 @@ abstract class DefaultRenderer<T>(
                 is RenderingStrategy.Copy -> outputWriter.writeResources(strategy.from, path)
                 is RenderingStrategy.Write -> outputWriter.write(path, strategy.text, "")
                 is RenderingStrategy.Callback -> outputWriter.write(path, strategy.instructions(this, page), ".html")
-                is RenderingStrategy.DriLocationResolvableWrite -> outputWriter.write(path, strategy.contentToResolve { dri, sourcesets ->
-                    locationProvider.resolve(dri, sourcesets)
-                }, "")
-                is RenderingStrategy.PageLocationResolvableWrite -> outputWriter.write(path, strategy.contentToResolve { pageToLocate, context ->
-                    locationProvider.resolve(pageToLocate, context)
-                }, "")
+                is RenderingStrategy.DriLocationResolvableWrite -> outputWriter.write(
+                    path,
+                    strategy.contentToResolve { dri, sourcesets ->
+                        locationProvider.resolve(dri, sourcesets)
+                    },
+                    ""
+                )
+                is RenderingStrategy.PageLocationResolvableWrite -> outputWriter.write(
+                    path,
+                    strategy.contentToResolve { pageToLocate, context ->
+                        locationProvider.resolve(pageToLocate, context)
+                    },
+                    ""
+                )
                 RenderingStrategy.DoNothing -> Unit
             }
             else -> throw AssertionError(
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentableMerger.kt b/plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentableMerger.kt
index 4c931230..94e27424 100644
--- a/plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentableMerger.kt
+++ b/plugins/base/src/main/kotlin/transformers/documentables/DefaultDocumentableMerger.kt
@@ -12,9 +12,8 @@ import org.jetbrains.kotlin.utils.addToStdlib.firstNotNullResult
 internal class DefaultDocumentableMerger(val context: DokkaContext) : DocumentableMerger {
     private val dependencyInfo = context.getDependencyInfo()
 
-    override fun invoke(modules: Collection<DModule>): DModule {
-
-        return modules.reduce { left, right ->
+    override fun invoke(modules: Collection<DModule>): DModule? =
+        modules.reduceOrNull { left, right ->
             val list = listOf(left, right)
             DModule(
                 name = modules.map { it.name }.distinct().joinToString("|"),
@@ -26,7 +25,6 @@ internal class DefaultDocumentableMerger(val context: DokkaContext) : Documentab
                 sourceSets = list.flatMap { it.sourceSets }.toSet()
             ).mergeExtras(left, right)
         }
-    }
 
     private fun DokkaContext.getDependencyInfo()
             : Map<DokkaConfiguration.DokkaSourceSet, List<DokkaConfiguration.DokkaSourceSet>> {
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/EmptyModulesFilterTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/EmptyModulesFilterTransformer.kt
new file mode 100644
index 00000000..fa31c5c3
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/documentables/EmptyModulesFilterTransformer.kt
@@ -0,0 +1,10 @@
+package org.jetbrains.dokka.base.transformers.documentables
+
+import org.jetbrains.dokka.model.DModule
+import org.jetbrains.dokka.transformers.documentation.PreMergeDocumentableTransformer
+
+class EmptyModulesFilterTransformer : PreMergeDocumentableTransformer {
+    override fun invoke(modules: List<DModule>): List<DModule> {
+        return modules.filter { it.children.isNotEmpty() }
+    }
+}
\ No newline at end of file
diff --git a/plugins/base/src/test/kotlin/basic/FailOnWarningTest.kt b/plugins/base/src/test/kotlin/basic/FailOnWarningTest.kt
index 2a3e4267..2a927b97 100644
--- a/plugins/base/src/test/kotlin/basic/FailOnWarningTest.kt
+++ b/plugins/base/src/test/kotlin/basic/FailOnWarningTest.kt
@@ -24,8 +24,9 @@ class FailOnWarningTest : BaseAbstractTest() {
         assertThrows<DokkaException> {
             testInline(
                 """
-                |/src/main/kotlin
+                |/src/main/kotlin/Bar.kt
                 |package sample
+                |class Bar {}
                 """.trimIndent(), configuration
             ) {
                 pluginsSetupStage = {
@@ -49,8 +50,9 @@ class FailOnWarningTest : BaseAbstractTest() {
         assertThrows<DokkaException> {
             testInline(
                 """
-                |/src/main/kotlin
+                |/src/main/kotlin/Bar.kt
                 |package sample
+                |class Bar {}
                 """.trimIndent(), configuration
             ) {
                 pluginsSetupStage = {
@@ -75,8 +77,9 @@ class FailOnWarningTest : BaseAbstractTest() {
 
         testInline(
             """
-                |/src/main/kotlin
+                |/src/main/kotlin/Bar.kt
                 |package sample
+                |class Bar {}
                 """.trimIndent(),
             configuration,
             loggerForTest = TestLogger(ZeroErrorOrWarningCountDokkaLogger())
@@ -99,8 +102,9 @@ class FailOnWarningTest : BaseAbstractTest() {
 
         testInline(
             """
-                |/src/main/kotlin
+                |/src/main/kotlin/Bar.kt
                 |package sample
+                |class Bar {}
                 """.trimIndent(), configuration
         ) {
             pluginsSetupStage = {
diff --git a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt
index cc5c2c29..ccb878d0 100644
--- a/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt
+++ b/plugins/base/src/test/kotlin/filter/DeprecationFilterTest.kt
@@ -31,7 +31,7 @@ class DeprecationFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 1
+                    it.first().packages.first().functions.size == 1
                 )
             }
         }
@@ -61,7 +61,7 @@ class DeprecationFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 1
+                    it.first().packages.first().functions.size == 1
                 )
             }
         }
@@ -91,7 +91,7 @@ class DeprecationFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 0
+                    it.first().packages.first().functions.size == 0
                 )
             }
         }
@@ -130,7 +130,7 @@ class DeprecationFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 0
+                    it.first().packages.first().functions.size == 0
                 )
             }
         }
@@ -167,7 +167,7 @@ class DeprecationFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 1
+                    it.first().packages.first().functions.size == 1
                 )
             }
         }
diff --git a/plugins/base/src/test/kotlin/filter/EmptyPackagesFilterTest.kt b/plugins/base/src/test/kotlin/filter/EmptyPackagesFilterTest.kt
index 356f66bf..2a5a5dd5 100644
--- a/plugins/base/src/test/kotlin/filter/EmptyPackagesFilterTest.kt
+++ b/plugins/base/src/test/kotlin/filter/EmptyPackagesFilterTest.kt
@@ -3,6 +3,7 @@ package filter
 import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.junit.jupiter.api.Assertions
 import org.junit.jupiter.api.Test
+import kotlin.test.assertEquals
 
 class EmptyPackagesFilterTest : BaseAbstractTest() {
     @Test
@@ -28,7 +29,7 @@ class EmptyPackagesFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.isNotEmpty()
+                    it.first().packages.isNotEmpty()
                 )
             }
         }
@@ -39,7 +40,7 @@ class EmptyPackagesFilterTest : BaseAbstractTest() {
             sourceSets {
                 sourceSet {
                     skipEmptyPackages = true
-                    sourceRoots = listOf("src/main/kotlin/basic/Test.kt")
+                    sourceRoots = listOf("src/main/kotlin")
                 }
             }
         }
@@ -49,15 +50,15 @@ class EmptyPackagesFilterTest : BaseAbstractTest() {
             |/src/main/kotlin/basic/Test.kt
             |package example
             |
-            |
+            | class ThisShouldBePresent { }
+            |/src/main/kotlin/empty/TestEmpty.kt
+            |package empty
         """.trimMargin(),
             configuration
         ) {
             documentablesFirstTransformationStep = { modules ->
                 modules.forEach { module ->
-                    Assertions.assertTrue(
-                        module.packages.isEmpty()
-                    )
+                    assertEquals(listOf("example"), module.packages.map { it.name })
                 }
             }
         }
diff --git a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt
index 13997154..b0476b6e 100644
--- a/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt
+++ b/plugins/base/src/test/kotlin/filter/VisibilityFilterTest.kt
@@ -33,7 +33,7 @@ class VisibilityFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 1
+                    it.first().packages.first().functions.size == 1
                 )
             }
         }
@@ -64,7 +64,7 @@ class VisibilityFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 0
+                    it.first().packages.first().functions.size == 0
                 )
             }
         }
@@ -95,7 +95,7 @@ class VisibilityFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 1
+                    it.first().packages.first().functions.size == 1
                 )
             }
         }
@@ -135,7 +135,7 @@ class VisibilityFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 1
+                    it.first().packages.first().functions.size == 1
                 )
             }
         }
@@ -175,7 +175,7 @@ class VisibilityFilterTest : BaseAbstractTest() {
         ) {
             documentablesFirstTransformationStep = {
                 Assertions.assertTrue(
-                    it.component2().packages.first().functions.size == 0
+                    it.first().packages.first().functions.size == 0
                 )
             }
         }
@@ -202,7 +202,7 @@ class VisibilityFilterTest : BaseAbstractTest() {
             configuration
         ) {
             documentablesFirstTransformationStep = {
-                assertEquals(0, it.component2().packages.first().typealiases.size)
+                assertEquals(0, it.first().packages.first().typealiases.size)
             }
         }
     }