Merge pull request #49 from Jolanrensen/Exclude-file-from-sources

`@file:ExcludeFromSources` support

.editorconfig

@@ -0,0 +1,38 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+max_line_length = 120
+
+[*.json]
+indent_size = 2
+
+[{*.yaml,*.yml}]
+indent_size = 2
+
+[*.ipynb]
+insert_final_newline = false
+
+[*.{kt,kts}]
+ij_kotlin_code_style_defaults = KOTLIN_OFFICIAL
+
+#  Disable wildcard imports entirely
+ij_kotlin_name_count_to_use_star_import = 2147483647
+ij_kotlin_name_count_to_use_star_import_for_members = 2147483647
+ij_kotlin_packages_to_use_import_on_demand = unset
+
+ktlint_code_style = ktlint_official
+ktlint_experimental = enabled
+ktlint_standard_filename = disabled
+ktlint_standard_no-empty-first-line-in-class-body = disabled
+ktlint_class_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than = 4
+ktlint_function_signature_rule_force_multiline_when_parameter_count_greater_or_equal_than = 4
+ktlint_ignore_back_ticked_identifier = true
+ktlint_standard_multiline-expression-wrapping = disabled
+
+[{*/build/**/*}]
+ktlint = disabled

doc-processor-gradle-plugin/src/functionalTest/kotlin/nl/jolanrensen/docProcessor/TestExcludeFromSources.kt

@@ -283,4 +283,74 @@ class TestExcludeFromSources : DocProcessorFunctionalTest(name = "excl") {
             ),
         ) shouldBe expectedOutput
     }
-}
+
+    @Test
+    fun file() {
+        @Language("kt")
+        val content = """
+            @file:ExcludeFromSources            
+            
+            package com.example.plugin
+            
+            
+            class HelloWorld {
+                /**
+                 * Hello World
+                 */
+                val helloWorld = "Hello World"
+            }
+            
+            /**
+             * {@include [HelloWorld.helloWorld]}!
+             */
+            fun helloWorld() {}
+        """.trimIndent()
+
+        processContent(
+            content = content,
+            packageName = "com.example.plugin",
+            processors = processors,
+            additionals = listOf(
+                AdditionalFile(
+                    relativePath = "src/main/kotlin/com/example/plugin/ExcludeFromSources.kt",
+                    content = annotationDef,
+                ),
+            ),
+        ) shouldBe null
+    }
+
+    @Test
+    fun `file 2`() {
+        @Language("kt")
+        val content = """
+            @file:[ExcludeFromSources ]            
+            
+            package com.example.plugin
+            
+            
+            class HelloWorld {
+                /**
+                 * Hello World
+                 */
+                val helloWorld = "Hello World"
+            }
+            
+            /**
+             * {@include [HelloWorld.helloWorld]}!
+             */
+            fun helloWorld() {}
+        """.trimIndent()
+
+        processContent(
+            content = content,
+            packageName = "com.example.plugin",
+            processors = processors,
+            additionals = listOf(
+                AdditionalFile(
+                    relativePath = "src/main/kotlin/com/example/plugin/ExcludeFromSources.kt",
+                    content = annotationDef,
+                ),
+            ),
+        ) shouldBe null
+    }
+}

doc-processor-gradle-plugin/src/main/kotlin/nl/jolanrensen/docProcessor/ProcessDocsAction.kt

@@ -58,29 +58,35 @@ abstract class ProcessDocsAction {
         // Find all processors
         val processors = findProcessors(parameters.processors, parameters.arguments)
 
-        if (processors.isEmpty())
+        if (processors.isEmpty()) {
             log.warn { "No processors found" }
-        else
+        } else {
             log.info { "Found processors: ${processors.map { it::class.qualifiedName }}" }
+        }
 
         // Run all processors
         val modifiedDocumentables =
-            processors.fold(sourceDocs) { acc, processor ->
-                log.lifecycle { "Running processor: ${processor::class.qualifiedName}..." }
-                val (docs, time) = measureTimedValue {
-                    processor.processSafely(processLimit = parameters.processLimit, documentablesByPath = acc)
-                }
-                log.lifecycle { "  - Finished in ${time.toString(DurationUnit.SECONDS)}." }
-                docs
-            }.documentablesToProcess
+            processors
+                .fold(sourceDocs) { acc, processor ->
+                    log.lifecycle { "Running processor: ${processor::class.qualifiedName}..." }
+                    val (docs, time) = measureTimedValue {
+                        processor.processSafely(processLimit = parameters.processLimit, documentablesByPath = acc)
+                    }
+                    log.lifecycle { "  - Finished in ${time.toString(DurationUnit.SECONDS)}." }
+                    docs
+                }.documentablesToProcess
 
         // filter to only include the modified documentables
         val modifiedDocumentablesPerFile = getModifiedDocumentablesPerFile(modifiedDocumentables)
 
         val documentablesToExcludeFromSourcesPerFile = getDocumentablesToExcludePerFile(modifiedDocumentables)
 
         log.info {
-            "Modified documentables: ${modifiedDocumentablesPerFile.values.flatMap { it.map { it.fullyQualifiedPath } }}"
+            "Modified documentables: ${
+                modifiedDocumentablesPerFile.values.flatMap {
+                    it.map { it.fullyQualifiedPath }
+                }
+            }"
         }
 
         // copy the sources to the target folder while replacing all docs in modified documentables
@@ -113,8 +119,9 @@ abstract class ProcessDocsAction {
         val context = dokkaGenerator.initializePlugins(configuration, logger, listOf(DokkaBase()))
         val translators = context[CoreExtensions.sourceToDocumentableTranslator]
             .filter {
-                it is DefaultPsiToDocumentableTranslator || // java
-                        it is DefaultDescriptorToDocumentableTranslator // kotlin
+                it is DefaultPsiToDocumentableTranslator ||
+                    // java
+                    it is DefaultDescriptorToDocumentableTranslator // kotlin
             }
 
         require(translators.any { it is DefaultPsiToDocumentableTranslator }) {
@@ -185,8 +192,7 @@ abstract class ProcessDocsAction {
                 it.value.filter {
                     it.isModified // filter out unmodified documentables
                 }
-            }
-            .groupBy { it.file }
+            }.groupBy { it.file }
 
     private fun getDocumentablesToExcludePerFile(
         modifiedSourceDocs: Map<String, List<DocumentableWrapper>>,
@@ -199,8 +205,23 @@ abstract class ProcessDocsAction {
                         it.simpleName == ExcludeFromSources::class.simpleName
                     }
                 }
+            }.groupBy { it.file }
+
+    /**
+     * Enables `@file:ExcludeFromSources` annotation to work.
+     */
+    private fun File.containsExcludeFromSources(): Boolean {
+        for (line in bufferedReader().lines()) {
+            val trimmed = line.trim()
+            when {
+                trimmed.startsWith("package") -> return false
+                trimmed.startsWith("import") -> return false
+                trimmed.contains("@file:${ExcludeFromSources::class.simpleName}") -> return true
+                trimmed.matches("@file:\\[.*${ExcludeFromSources::class.simpleName}.*]".toRegex()) -> return true
             }
-            .groupBy { it.file }
+        }
+        return false
+    }
 
     @Throws(IOException::class)
     private fun copyAndModifySources(
@@ -210,6 +231,7 @@ abstract class ProcessDocsAction {
         for (source in parameters.sourceRoots) {
             for (file in source.walkTopDown()) {
                 if (!file.isFile) continue
+                if (file.containsExcludeFromSources()) continue
 
                 val relativePath = parameters.baseDir.toPath().relativize(file.toPath())
                 val targetFile = File(parameters.target, relativePath.toString())
@@ -223,7 +245,8 @@ abstract class ProcessDocsAction {
                 }
 
                 val fileContent = try {
-                    file.readText()
+                    file
+                        .readText()
                         .replace("\r\n", "\n")
                         .replace("\r", "\n")
                 } catch (e: Exception) {
@@ -258,7 +281,7 @@ abstract class ProcessDocsAction {
                     }
 
                 val processedFileContent = fileContent.replaceNonOverlappingRanges(
-                    *(docModificationsByRange + exclusionModificationsByRange).toTypedArray()
+                    *(docModificationsByRange + exclusionModificationsByRange).toTypedArray(),
                 )
 
                 try {
@@ -376,4 +399,4 @@ abstract class ProcessDocsAction {
             else -> error("Unreachable")
         }
     }
-}
+}