@comment tag, indent fixes

README.md

@@ -13,6 +13,7 @@ Examples include:
  - `@include` tag to include other comments into your KDoc / JavaDoc, see [@include Processor](#include-processor) (`INCLUDE_DOC_PROCESSOR`)
  - `@sample` / `@sampleNoComments` tag to include code samples into your KDoc / JavaDoc (`SAMPLE_DOC_PROCESSOR`)
  - `@includeFile` tag to include file content into your KDoc / JavaDoc (`INCLUDE_FILE_DOC_PROCESSOR`)
+ - `@comment` tag to comment out parts of your modified KDoc / JavaDoc (`COMMENT_DOC_PROCESSOR`)
  - A processor that removes all KDoc / JavaDoc comments (`NO_DOC_PROCESSOR`)
  - A processor that adds a `/** TODO */` comment wherever there is no KDoc / JavaDoc comment (`TODO_DOC_PROCESSOR`)
  - A processor that makes all KDoc / JavaDoc comments uppercase (try and make this for fun!)

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

@@ -0,0 +1,56 @@
+package nl.jolanrensen.docProcessor.defaultProcessors
+
+import nl.jolanrensen.docProcessor.DocumentableWithSource
+import nl.jolanrensen.docProcessor.TagDocProcessor
+
+/**
+ * @see CommentDocProcessor
+ */
+const val COMMENT_DOC_PROCESSOR = "nl.jolanrensen.docProcessor.defaultProcessors.CommentDocProcessor"
+
+/**
+ * Adds `{@comment tags}` that will be removed from the docs upon processing.
+ *
+ * For example:
+ * ```kotlin
+ * /**
+ * * {@comment This is a comment}
+ * * This is not a comment
+ * * @comment This is also a comment
+ * * and this too
+ * * @otherTag This is not a comment
+ * */
+ * ```
+ * would turn into
+ * ```kotlin
+ * /**
+ * * This is not a comment
+ * *
+ * * @otherTag This is not a comment
+ * */
+ * ```
+ */
+class CommentDocProcessor : TagDocProcessor() {
+
+    private val tag = "comment"
+    override fun tagIsSupported(tag: String): Boolean =
+        tag == this.tag
+
+    override fun processTagWithContent(
+        tagWithContent: String,
+        path: String,
+        documentable: DocumentableWithSource,
+        docContent: String,
+        filteredDocumentables: Map<String, List<DocumentableWithSource>>,
+        allDocumentables: Map<String, List<DocumentableWithSource>>
+    ): String = ""
+
+    override fun processInnerTagWithContent(
+        tagWithContent: String,
+        path: String,
+        documentable: DocumentableWithSource,
+        docContent: String,
+        filteredDocumentables: Map<String, List<DocumentableWithSource>>,
+        allDocumentables: Map<String, List<DocumentableWithSource>>
+    ): String = ""
+}

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

@@ -16,17 +16,20 @@ const val INCLUDE_DOC_PROCESSOR = "nl.jolanrensen.docProcessor.defaultProcessors
 
 /**
  * Allows you to @include docs from other linkable elements.
+ * `@include` keeps the content of the block below the include statement intact.
  *
  * For example:
  * ```kotlin
  * /**
  *  * @include [SomeClass]
+ *  * Hi
  *  */
  * ```
  * would turn into
  * ```kotlin
  * /**
  *  * This is the docs of SomeClass
+ *  * Hi
  *  */
  */
 class IncludeDocProcessor : TagDocProcessor() {

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

@@ -16,6 +16,8 @@ const val INCLUDE_FILE_DOC_PROCESSOR = "nl.jolanrensen.docProcessor.defaultProce
  * For example:
  * `@includeFile (../../someFile.txt)`
  *
+ * `@includeFile` keeps the content of the block below the includeFile statement intact.
+ *
  * TODO include settings for filtering in the file, optional triple quotes, etc.
  */
 class IncludeFileDocProcessor : TagDocProcessor() {

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

@@ -29,6 +29,8 @@ const val SAMPLE_DOC_PROCESSOR = "nl.jolanrensen.docProcessor.defaultProcessors.
  *
  * For KDoc, the code will be presented as a Markdown code block with syntax highlighting depending on the language you
  * target.
+ *
+ * `@sample` and `@sampleNoComments` keeps the content of the block below the statement intact.
  */
 class SampleDocProcessor : TagDocProcessor() {
 

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

@@ -7,11 +7,14 @@ fun String.getDocContent() = this
     .split('\n')
     .joinToString("\n") {
         it
-            .trim()
+            .trimStart()
             .removePrefix("/**")
             .removeSuffix("*/")
             .removePrefix("*")
-            .trim()
+            .let {
+                if (it.startsWith(" ")) it.drop(1)
+                else it
+            }
     }
 
 

doc-processor-gradle-plugin/src/main/resources/META-INF/services/nl.jolanrensen.docProcessor.DocProcessor

@@ -3,4 +3,5 @@ nl.jolanrensen.docProcessor.defaultProcessors.NoDocProcessor
 nl.jolanrensen.docProcessor.defaultProcessors.TodoDocProcessor
 nl.jolanrensen.docProcessor.defaultProcessors.SampleDocProcessor
 nl.jolanrensen.docProcessor.defaultProcessors.ExampleDocProcessor
-nl.jolanrensen.docProcessor.defaultProcessors.IncludeFileDocProcessor
+nl.jolanrensen.docProcessor.defaultProcessors.IncludeFileDocProcessor
+nl.jolanrensen.docProcessor.defaultProcessors.CommentDocProcessor

doc-processor-gradle-plugin/src/test/kotlin/nl/jolanrensen/docProcessor/DocProcessorPluginTest.kt

@@ -2,7 +2,6 @@ package nl.jolanrensen.docProcessor
 
 import io.kotest.matchers.shouldBe
 import org.gradle.testfixtures.ProjectBuilder
-import org.junit.Assert
 import org.junit.Test
 
 class DocProcessorPluginTest {
@@ -11,9 +10,6 @@ class DocProcessorPluginTest {
         // Create a test project and apply the plugin
         val project = ProjectBuilder.builder().build()
         project.plugins.apply("nl.jolanrensen.docProcessor")
-
-        // Verify the result
-//        Assert.assertNotNull(project.tasks.findByName("processKdocInclude"))
     }
 
     /**
@@ -30,7 +26,7 @@ class DocProcessorPluginTest {
      * ```
      * @g Test
      */
-    private val text =
+    private val difficultKdoc =
         """|blablah
            |  @a a
            |Some extra text. @b nothing, this is skipped
@@ -63,8 +59,8 @@ class DocProcessorPluginTest {
             """|@g Test""",
         ).map { it.trimMargin() }
 
-        text.splitDocContent() shouldBe expected
-        text.splitDocContent().joinToString("\n") shouldBe text
+        difficultKdoc.splitDocContent() shouldBe expected
+        difficultKdoc.splitDocContent().joinToString("\n") shouldBe difficultKdoc
     }
 
     @Test
@@ -88,15 +84,15 @@ class DocProcessorPluginTest {
                |@g Test"""
         ).map { it.trimMargin() }
 
-        text.splitDocContentOnInnerTags() shouldBe expected
-        text.splitDocContentOnInnerTags().joinToString("") shouldBe text
+        difficultKdoc.splitDocContentOnInnerTags() shouldBe expected
+        difficultKdoc.splitDocContentOnInnerTags().joinToString("") shouldBe difficultKdoc
     }
 
     @Test
     fun `Test Kdoc utils`() {
         val kdoc1 = """
             /**
-             * Hello World!
+             *       Hello World!
              * 
              * @see [com.example.plugin.KdocIncludePlugin]
              */
@@ -132,6 +128,22 @@ class DocProcessorPluginTest {
         """.trimIndent()
 
         kdoc5.getDocContent().toDoc() shouldBe kdoc5
+
+        // this is not a pretty kdoc, but we can still parse it and correct the indentation
+        val kdoc6 = """
+            /**
+             *Hello World!
+             */
+        """.trimIndent()
+
+        val kdoc6a = """
+            /**
+             * Hello World!
+             */
+        """.trimIndent()
+
+
+        kdoc6.getDocContent().toDoc() shouldBe kdoc6a
     }
 }