Implement ParseModuleAndPackageDocFragments API

3 files changed, 102 insertions, 24 deletions

diff --git a/plugins/base/src/main/kotlin/parsers/ModuleAndPackageDocumentationParser.kt b/plugins/base/src/main/kotlin/parsers/ModuleAndPackageDocumentationParser.kt
new file mode 100644
index 00000000..4b46537b
--- /dev/null
+++ b/plugins/base/src/main/kotlin/parsers/ModuleAndPackageDocumentationParser.kt
@@ -0,0 +1,76 @@
+package org.jetbrains.dokka.base.parsers
+
+import org.jetbrains.dokka.DokkaException
+import java.io.File
+
+internal class IllegalModuleAndPackageDocumentation(
+    source: ModuleAndPackageDocumentationSource, message: String
+) : DokkaException("[$source] $message")
+
+data class ModuleAndPackageDocFragment(
+    val classifier: Classifier,
+    val name: String,
+    val documentation: String
+) {
+    enum class Classifier { Module, Package }
+}
+
+internal abstract class ModuleAndPackageDocumentationSource {
+    abstract val sourceDescription: String
+    abstract val documentation: String
+
+    override fun toString(): String {
+        return sourceDescription
+    }
+}
+
+internal class ModuleAndPackageDocumentationFile(private val file: File) : ModuleAndPackageDocumentationSource() {
+    override val sourceDescription: String = file.path
+    override val documentation: String by lazy(LazyThreadSafetyMode.PUBLICATION) { file.readText() }
+}
+
+internal fun parseModuleAndPackageDocFragments(source: File): List<ModuleAndPackageDocFragment> {
+    return parseModuleAndPackageDocFragments(ModuleAndPackageDocumentationFile(source))
+}
+
+internal fun parseModuleAndPackageDocFragments(source: ModuleAndPackageDocumentationSource): List<ModuleAndPackageDocFragment> {
+    val fragmentStrings = source.documentation.split(Regex("(|^)#\\s*(?=(Module|Package))"))
+    return fragmentStrings
+        .filter(String::isNotBlank)
+        .map { fragmentString -> parseModuleAndPackageDocFragment(source, fragmentString) }
+}
+
+private fun parseModuleAndPackageDocFragment(
+    source: ModuleAndPackageDocumentationSource,
+    fragment: String
+): ModuleAndPackageDocFragment {
+    val firstLineAndDocumentation = fragment.split("\r\n", "\n", "\r", limit = 2)
+    val firstLine = firstLineAndDocumentation[0]
+
+    val classifierAndName = firstLine.split(Regex("\\s+"), limit = 2)
+    if (classifierAndName.size != 2) {
+        throw IllegalModuleAndPackageDocumentation(source, "Missing ${classifierAndName.first()} name")
+    }
+
+    val classifier = when (classifierAndName[0].trim()) {
+        "Module" -> ModuleAndPackageDocFragment.Classifier.Module
+        "Package" -> ModuleAndPackageDocFragment.Classifier.Package
+        else -> throw IllegalStateException("Unexpected classifier ${classifierAndName[0]}")
+    }
+
+    val name = classifierAndName[1].trim()
+    if (name.contains(Regex("\\s"))) {
+        throw IllegalModuleAndPackageDocumentation(
+            source, "Module/Package name cannot contain whitespace in '$firstLine'"
+        )
+    }
+
+    return ModuleAndPackageDocFragment(
+        classifier = classifier,
+        name = name,
+        documentation = firstLineAndDocumentation.getOrNull(1)?.trim().orEmpty()
+    )
+}
+
+
+
diff --git a/plugins/base/src/main/kotlin/parsers/Parser.kt b/plugins/base/src/main/kotlin/parsers/Parser.kt
index 1dd0c34a..706f093b 100644
--- a/plugins/base/src/main/kotlin/parsers/Parser.kt
+++ b/plugins/base/src/main/kotlin/parsers/Parser.kt
@@ -5,6 +5,7 @@ import org.jetbrains.dokka.model.doc.*
 abstract class Parser {
 
     abstract fun parseStringToDocNode(extractedString: String): DocTag
+
     abstract fun preparse(text: String): String
 
     fun parse(text: String): DocumentationNode {
@@ -12,22 +13,28 @@ abstract class Parser {
         val list = jkdocToListOfPairs(preparse(text))
 
         val mappedList: List<TagWrapper> = list.map {
-            when(it.first) {
-                "description"         -> Description(parseStringToDocNode(it.second))
-                "author"              -> Author(parseStringToDocNode(it.second))
-                "version"             -> Version(parseStringToDocNode(it.second))
-                "since"               -> Since(parseStringToDocNode(it.second))
-                "see"                 -> See(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '), null)
-                "param"               -> Param(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
-                "property"            -> Property(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
-                "return"              -> Return(parseStringToDocNode(it.second))
-                "constructor"         -> Constructor(parseStringToDocNode(it.second))
-                "receiver"            -> Receiver(parseStringToDocNode(it.second))
-                "throws", "exception" -> Throws(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
-                "deprecated"          -> Deprecated(parseStringToDocNode(it.second))
-                "sample"              -> Sample(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
-                "suppress"            -> Suppress(parseStringToDocNode(it.second))
-                else                  -> CustomTagWrapper(parseStringToDocNode(it.second), it.first)
+            when (it.first) {
+                "description" -> Description(parseStringToDocNode(it.second))
+                "author" -> Author(parseStringToDocNode(it.second))
+                "version" -> Version(parseStringToDocNode(it.second))
+                "since" -> Since(parseStringToDocNode(it.second))
+                "see" -> See(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '), null)
+                "param" -> Param(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
+                "property" -> Property(
+                    parseStringToDocNode(it.second.substringAfter(' ')),
+                    it.second.substringBefore(' ')
+                )
+                "return" -> Return(parseStringToDocNode(it.second))
+                "constructor" -> Constructor(parseStringToDocNode(it.second))
+                "receiver" -> Receiver(parseStringToDocNode(it.second))
+                "throws", "exception" -> Throws(
+                    parseStringToDocNode(it.second.substringAfter(' ')),
+                    it.second.substringBefore(' ')
+                )
+                "deprecated" -> Deprecated(parseStringToDocNode(it.second))
+                "sample" -> Sample(parseStringToDocNode(it.second.substringAfter(' ')), it.second.substringBefore(' '))
+                "suppress" -> Suppress(parseStringToDocNode(it.second))
+                else -> CustomTagWrapper(parseStringToDocNode(it.second), it.first)
             }
         }
         return DocumentationNode(mappedList)
@@ -39,4 +46,4 @@ abstract class Parser {
             .map {
                 it.substringBefore(' ') to it.substringAfter(' ')
             }
-}
\ No newline at end of file
+}
diff --git a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
index 71824922..5f1a540d 100644
--- a/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
+++ b/plugins/base/src/main/kotlin/transformers/documentables/ModuleAndPackageDocumentationTransformer.kt
@@ -37,12 +37,7 @@ internal class ModuleAndPackageDocumentationTransformer(
                                         .readText()
                                         .split(Regex("(\n|^)# (?=(Module|Package))")) // Matches heading with Module/Package to split by
                                         .filter { it.isNotEmpty() }
-                                        .map {
-                                            it.split(
-                                                Regex(" "),
-                                                2
-                                            )
-                                        } // Matches space between Module/Package and fully qualified name
+                                        .map { it.split(Regex(" "), 2) } // Matches space between Module/Package and fully qualified name
                                 }.groupBy({ it[0] }, {
                                     it[1].split(Regex("\n"), 2) // Matches new line after fully qualified name
                                         .let { it[0].trim() to it[1].trim() }
@@ -99,7 +94,7 @@ internal class ModuleAndPackageDocumentationTransformer(
         }
     }
 
-    private fun mergeDocumentation(origin: Map<DokkaSourceSet, DocumentationNode>, new: Map<DokkaSourceSet, DocumentationNode>) =
+    private fun mergeDocumentation(origin: Map<DokkaSourceSet, DocumentationNode>, new: Map<DokkaSourceSet, DocumentationNode>): Map<DokkaSourceSet, DocumentationNode> =
         (origin.asSequence() + new.asSequence())
             .distinct()
             .groupBy({ it.key }, { it.value })