Add explicit exceptions in markdown and allow for empty link destinations (#1757)

2 files changed, 137 insertions, 0 deletions

diff --git a/plugins/base/src/test/kotlin/markdown/ParserTest.kt b/plugins/base/src/test/kotlin/markdown/ParserTest.kt
index 0fdb10c1..4ac4a43f 100644
--- a/plugins/base/src/test/kotlin/markdown/ParserTest.kt
+++ b/plugins/base/src/test/kotlin/markdown/ParserTest.kt
@@ -5,6 +5,9 @@ import org.intellij.markdown.MarkdownElementTypes
 import org.jetbrains.dokka.model.doc.*
 import org.junit.jupiter.api.Disabled
 import org.junit.jupiter.api.Test
+import org.junit.jupiter.api.assertThrows
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
 
 
 class ParserTest : KDocTest() {
@@ -1437,5 +1440,46 @@ class ParserTest : KDocTest() {
         )
         executeTest(kdoc, expectedDocumentationNode)
     }
+
+    @Test
+    fun `short link without destination`() {
+        val kdoc = """
+        | This is [link]()
+        """.trimMargin()
+        val expectedDocumentationNode = DocumentationNode(
+            listOf(
+                Description(
+                    CustomDocTag(
+                        listOf(
+                            P(
+                                listOf(
+                                    Text("This is "),
+                                    A(
+                                        listOf(Text("link")),
+                                        mapOf("href" to "")
+                                    )
+                                )
+                            )
+                        ), name = MarkdownElementTypes.MARKDOWN_FILE.name
+                    )
+                )
+            )
+        )
+        executeTest(kdoc, expectedDocumentationNode)
+    }
+
+    @Test
+    fun `exception thrown by empty header should point to location of a file`() {
+        val kdoc = """
+        | ###
+        """.trimMargin()
+        val expectedDocumentationNode = DocumentationNode(emptyList())
+        val exception = runCatching { executeTest(kdoc, expectedDocumentationNode) }.exceptionOrNull()
+
+        assertEquals(
+            "Wrong AST Tree. Header does not contain expected content in Test.kt/example.Test, element starts from offset 0 and ends 3: ###",
+            exception?.message
+        )
+    }
 }
 
diff --git a/plugins/base/src/test/kotlin/transformers/InvalidContentModuleAndPackageDocumentationReaderTest.kt b/plugins/base/src/test/kotlin/transformers/InvalidContentModuleAndPackageDocumentationReaderTest.kt
new file mode 100644
index 00000000..b9837750
--- /dev/null
+++ b/plugins/base/src/test/kotlin/transformers/InvalidContentModuleAndPackageDocumentationReaderTest.kt
@@ -0,0 +1,93 @@
+package transformers
+
+import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationReader
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.utilities.DokkaConsoleLogger
+import org.junit.jupiter.api.BeforeEach
+import org.junit.jupiter.api.Test
+import testApi.testRunner.TestDokkaConfigurationBuilder
+import testApi.testRunner.dModule
+import kotlin.test.assertEquals
+import kotlin.test.assertTrue
+
+
+class InvalidContentModuleAndPackageDocumentationReaderTest : AbstractContextModuleAndPackageDocumentationReaderTest() {
+
+    private val includeA by lazy { temporaryDirectory.resolve("includeA.md").toFile() }
+    private val includeB by lazy { temporaryDirectory.resolve("includeB.md").toFile() }
+
+    @BeforeEach
+    fun materializeInclude() {
+        includeA.writeText(
+            """
+            Invalid random stuff 
+            
+            # Module moduleA
+            Simple stuff
+            """.trimIndent()
+        )
+        includeB.writeText(
+            """
+            # Module moduleB
+            ###
+            """.trimIndent()
+        )
+    }
+
+    private val configurationBuilderA = TestDokkaConfigurationBuilder().apply {
+        moduleName = "moduleA"
+    }
+    private val configurationBuilderB = TestDokkaConfigurationBuilder().apply {
+        moduleName = "moduleB"
+    }
+
+    private val sourceSetA by configurationBuilderA.sourceSet {
+        includes = listOf(includeA.canonicalPath)
+    }
+
+    private val sourceSetB by configurationBuilderB.sourceSet {
+        includes = listOf(includeB.canonicalPath)
+    }
+
+    private val contextA by lazy {
+        DokkaContext.create(
+            configuration = configurationBuilderA.build(),
+            logger = DokkaConsoleLogger,
+            pluginOverrides = emptyList()
+        )
+    }
+    private val contextB by lazy {
+        DokkaContext.create(
+            configuration = configurationBuilderB.build(),
+            logger = DokkaConsoleLogger,
+            pluginOverrides = emptyList()
+        )
+    }
+
+    private val readerA by lazy { ModuleAndPackageDocumentationReader(contextA) }
+    private val readerB by lazy { ModuleAndPackageDocumentationReader(contextB) }
+
+
+    @Test
+    fun `parsing should fail with a message when documentation is in not proper format`() {
+        val exception =
+            runCatching { readerA[dModule(name = "moduleA", sourceSets = setOf(sourceSetA))] }.exceptionOrNull()
+        assertEquals(
+            "Unexpected classifier: \"Invalid\", expected either \"Module\" or \"Package\". \n" +
+                    "For more information consult the specification: https://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation",
+            exception?.message
+        )
+    }
+
+    @Test
+    fun `parsing should fail with a message where it encountered error and why`() {
+        val exception =
+            runCatching { readerB[dModule(name = "moduleB", sourceSets = setOf(sourceSetB))] }.exceptionOrNull()?.message!!
+
+        //I don't want to assert whole message since it contains a path to a temporary folder
+        assertTrue(exception.contains("Wrong AST Tree. Header does not contain expected content in "))
+        assertTrue(exception.contains("includeB.md"))
+        assertTrue(exception.contains("element starts from offset 0 and ends 3: ###"))
+    }
+}
+