Description list support for JavaDocs (#2213)

3 files changed, 197 insertions, 5 deletions

diff --git a/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt b/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt
index e6e1e105..c066075a 100644
--- a/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt
+++ b/plugins/base/src/test/kotlin/parsers/JavadocParserTest.kt
@@ -5,10 +5,9 @@ import org.jetbrains.dokka.base.testApi.testRunner.BaseAbstractTest
 import org.jetbrains.dokka.model.DEnum
 import org.jetbrains.dokka.model.DModule
 import org.jetbrains.dokka.model.doc.*
-import org.jetbrains.dokka.model.doc.P
 import org.junit.jupiter.api.Assertions.assertEquals
 import org.junit.jupiter.api.Test
-import utils.*
+import utils.text
 
 class JavadocParserTest : BaseAbstractTest() {
 
@@ -249,4 +248,105 @@ class JavadocParserTest : BaseAbstractTest() {
             }
         }
     }
+
+    @Test
+    fun `description list tag`() {
+        val source = """
+            |/src/main/kotlin/test/Test.java
+            |package example
+            |
+            | /**
+            | * <dl>
+            | *     <dt>
+            | *         <code>name="<i>name</i>"</code>
+            | *     </dt>
+            | *     <dd>
+            | *         A URI path segment. The subdirectory name for this value is contained in the
+            | *         <code>path</code> attribute.
+            | *     </dd>
+            | *     <dt>
+            | *         <code>path="<i>path</i>"</code>
+            | *     </dt>
+            | *     <dd>
+            | *         The subdirectory you're sharing. While the <i>name</i> attribute is a URI path
+            | *         segment, the <i>path</i> value is an actual subdirectory name. 
+            | *     </dd>
+            | * </dl>
+            | */
+            | public class Test  {}
+            """.trimIndent()
+
+        val expected = listOf(
+            Dl(
+                listOf(
+                    Dt(
+                        listOf(
+                            CodeInline(
+                                listOf(
+                                    Text("name=\""),
+                                    I(
+                                        listOf(
+                                            Text("name")
+                                        )
+                                    ),
+                                    Text("\"")
+                                )
+                            ),
+                        )
+                    ),
+                    Dd(
+                        listOf(
+                            Text(" A URI path segment. The subdirectory name for this value is contained in the "),
+                            CodeInline(
+                                listOf(
+                                    Text("path")
+                                )
+                            ),
+                            Text(" attribute. ")
+                        )
+                    ),
+
+                    Dt(
+                        listOf(
+                            CodeInline(
+                                listOf(
+                                    Text("path=\""),
+                                    I(
+                                        listOf(
+                                            Text("path")
+                                        )
+                                    ),
+                                    Text("\"")
+                                )
+                            )
+                        )
+                    ),
+                    Dd(
+                        listOf(
+                            Text(" The subdirectory you're sharing. While the "),
+                            I(
+                                listOf(
+                                    Text("name")
+                                )
+                            ),
+                            Text(" attribute is a URI path segment, the "),
+                            I(
+                                listOf(
+                                    Text("path")
+                                )
+                            ),
+                            Text(" value is an actual subdirectory name. ")
+                        )
+                    )
+                )
+            )
+        )
+
+        testInline(source, configuration) {
+            documentablesCreationStage = { modules ->
+                val docs = modules.first().packages.first().classlikes.single().documentation.first().value
+                assertEquals(expected, docs.children.first().root.children)
+            }
+        }
+    }
 }
diff --git a/plugins/base/src/test/kotlin/renderers/html/ListStylesTest.kt b/plugins/base/src/test/kotlin/renderers/html/ListStylesTest.kt
new file mode 100644
index 00000000..d578ba5e
--- /dev/null
+++ b/plugins/base/src/test/kotlin/renderers/html/ListStylesTest.kt
@@ -0,0 +1,41 @@
+package renderers.html
+
+import org.jetbrains.dokka.base.renderers.html.HtmlRenderer
+import org.jetbrains.dokka.pages.ListStyle
+import org.junit.jupiter.api.Test
+import renderers.testPage
+import utils.Dd
+import utils.Dl
+import utils.Dt
+import utils.match
+
+
+class ListStylesTest : HtmlRenderingOnlyTestBase() {
+
+    @Test
+    fun `description list render`() {
+        val page = testPage {
+            descriptionList {
+                item(styles = setOf(ListStyle.DescriptionTerm)) {
+                    text("Description term #1")
+                }
+                item(styles = setOf(ListStyle.DescriptionTerm)) {
+                    text("Description term #2")
+                }
+                item(styles = setOf(ListStyle.DescriptionDetails)) {
+                    text("Description details describing terms #1 and #2")
+                }
+            }
+        }
+
+
+        HtmlRenderer(context).render(page)
+        renderedContent.match(
+            Dl(
+                Dt("Description term #1"),
+                Dt("Description term #2"),
+                Dd("Description details describing terms #1 and #2")
+            )
+        )
+    }
+}
\ No newline at end of file
diff --git a/plugins/base/src/test/kotlin/transformers/CommentsToContentConverterTest.kt b/plugins/base/src/test/kotlin/transformers/CommentsToContentConverterTest.kt
index 8703a4a9..6d8730f1 100644
--- a/plugins/base/src/test/kotlin/transformers/CommentsToContentConverterTest.kt
+++ b/plugins/base/src/test/kotlin/transformers/CommentsToContentConverterTest.kt
@@ -1,13 +1,14 @@
 package transformers
 
+import matchers.content.*
 import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConverter
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.doc.*
-import org.junit.jupiter.api.Assertions.*
-import org.junit.jupiter.api.Test
-import matchers.content.*
 import org.jetbrains.dokka.pages.*
 import org.jetbrains.kotlin.utils.addToStdlib.assertedCast
+import org.junit.jupiter.api.Assertions.assertEquals
+import org.junit.jupiter.api.Assertions.assertTrue
+import org.junit.jupiter.api.Test
 
 class CommentsToContentConverterTest {
     private val converter = DocTagToContentConverter()
@@ -422,4 +423,54 @@ class CommentsToContentConverterTest {
             }
         }
     }
+
+    @Test
+    fun `description list`() {
+        val docTag =
+            Dl(
+                listOf(
+                    Dt(
+                        listOf(
+                            Text("description list can have...")
+                        )
+                    ),
+                    Dt(
+                        listOf(
+                            Text("... two consecutive description terms")
+                        )
+                    ),
+                    Dd(
+                        listOf(
+                            Text("and usually has some sort of a description, like this one")
+                        )
+                    )
+                )
+            )
+
+        executeTest(docTag) {
+            composite<ContentList> {
+                check {
+                    assertTrue(style.contains(ListStyle.DescriptionList)) { "Expected DL style" }
+                }
+                group {
+                    check {
+                        assertTrue(style.contains(ListStyle.DescriptionTerm)) { "Expected DT style" }
+                    }
+                    +"description list can have..."
+                }
+                group {
+                    check {
+                        assertTrue(style.contains(ListStyle.DescriptionTerm)) { "Expected DT style" }
+                    }
+                    +"... two consecutive description terms"
+                }
+                group {
+                    check {
+                        assertTrue(style.contains(ListStyle.DescriptionDetails)) { "Expected DD style" }
+                    }
+                    +"and usually has some sort of a description, like this one"
+                }
+            }
+        }
+    }
 }
\ No newline at end of file