From c68c05a1e8876e9b8555df7bcdfeaca3e100f0d1 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Mon, 6 Dec 2021 16:20:51 +0300 Subject: [PATCH 1/3] Description list support for JavaDocs (#2213) --- core/api/core.api | 8 ++ core/src/main/kotlin/pages/ContentNodes.kt | 22 ++++ plugins/base/api/base.api | 4 + .../base-test-utils/api/base-test-utils.api | 12 ++ .../src/main/kotlin/renderers/JsoupUtils.kt | 3 + .../kotlin/renderers/html/HtmlRenderer.kt | 28 ++++- .../comments/DocTagToContentConverter.kt | 25 ++++- .../documentables/PageContentBuilder.kt | 12 ++ .../translators/psi/parsers/JavadocParser.kt | 11 +- .../test/kotlin/parsers/JavadocParserTest.kt | 104 +++++++++++++++++- .../kotlin/renderers/html/ListStylesTest.kt | 41 +++++++ .../CommentsToContentConverterTest.kt | 57 +++++++++- 12 files changed, 313 insertions(+), 14 deletions(-) create mode 100644 plugins/base/src/test/kotlin/renderers/html/ListStylesTest.kt diff --git a/core/api/core.api b/core/api/core.api index 96fe317a1e..46a4c3a561 100644 --- a/core/api/core.api +++ b/core/api/core.api @@ -3913,6 +3913,14 @@ public final class org/jetbrains/dokka/pages/HtmlContent : org/jetbrains/dokka/m public abstract interface class org/jetbrains/dokka/pages/Kind { } +public final class org/jetbrains/dokka/pages/ListStyle : java/lang/Enum, org/jetbrains/dokka/pages/Style { + public static final field DescriptionDetails Lorg/jetbrains/dokka/pages/ListStyle; + public static final field DescriptionList Lorg/jetbrains/dokka/pages/ListStyle; + public static final field DescriptionTerm Lorg/jetbrains/dokka/pages/ListStyle; + public static fun valueOf (Ljava/lang/String;)Lorg/jetbrains/dokka/pages/ListStyle; + public static fun values ()[Lorg/jetbrains/dokka/pages/ListStyle; +} + public abstract interface class org/jetbrains/dokka/pages/MemberPage : org/jetbrains/dokka/pages/ContentPage { } diff --git a/core/src/main/kotlin/pages/ContentNodes.kt b/core/src/main/kotlin/pages/ContentNodes.kt index 0c262937d7..c1bb3b8cca 100644 --- a/core/src/main/kotlin/pages/ContentNodes.kt +++ b/core/src/main/kotlin/pages/ContentNodes.kt @@ -350,6 +350,28 @@ enum class ContentStyle : Style { RowTitle, TabbedContent, WithExtraAttributes, RunnableSample, InDocumentationAnchor, Caption } +enum class ListStyle : Style { + /** + * Represents a list of groups of [DescriptionTerm] and [DescriptionDetails]. + * Common uses for this element are to implement a glossary or to display + * metadata (a list of key-value pairs). Formatting example: see `
` html tag. + */ + DescriptionList, + + /** + * If used within [DescriptionList] context, specifies a term in a description + * or definition list, usually followed by [DescriptionDetails] for one or more + * terms. Formatting example: see `
` html tag + */ + DescriptionTerm, + + /** + * If used within [DescriptionList] context, provides the definition or other + * related text associated with [DescriptionTerm]. Formatting example: see `
` html tag + */ + DescriptionDetails +} + object CommentTable : Style object MultimoduleTable : Style diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 5a7573eec8..79f123669d 100644 --- a/plugins/base/api/base.api +++ b/plugins/base/api/base.api @@ -351,8 +351,10 @@ public class org/jetbrains/dokka/base/renderers/html/HtmlRenderer : org/jetbrain public static synthetic fun buildLink$default (Lorg/jetbrains/dokka/base/renderers/html/HtmlRenderer;Lkotlinx/html/FlowContent;Lorg/jetbrains/dokka/links/DRI;Ljava/util/List;Lorg/jetbrains/dokka/pages/PageNode;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V public synthetic fun buildList (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/ContentList;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V public fun buildList (Lkotlinx/html/FlowContent;Lorg/jetbrains/dokka/pages/ContentList;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V + public fun buildListItems (Lkotlinx/html/DL;Ljava/util/List;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V public fun buildListItems (Lkotlinx/html/OL;Ljava/util/List;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V public fun buildListItems (Lkotlinx/html/UL;Ljava/util/List;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;)V + public static synthetic fun buildListItems$default (Lorg/jetbrains/dokka/base/renderers/html/HtmlRenderer;Lkotlinx/html/DL;Ljava/util/List;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;ILjava/lang/Object;)V public static synthetic fun buildListItems$default (Lorg/jetbrains/dokka/base/renderers/html/HtmlRenderer;Lkotlinx/html/OL;Ljava/util/List;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;ILjava/lang/Object;)V public static synthetic fun buildListItems$default (Lorg/jetbrains/dokka/base/renderers/html/HtmlRenderer;Lkotlinx/html/UL;Ljava/util/List;Lorg/jetbrains/dokka/pages/ContentPage;Ljava/util/Set;ILjava/lang/Object;)V public synthetic fun buildNavigation (Ljava/lang/Object;Lorg/jetbrains/dokka/pages/PageNode;)V @@ -1398,6 +1400,8 @@ public class org/jetbrains/dokka/base/translators/documentables/PageContentBuild public final fun cover (Ljava/lang/String;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;)V public static synthetic fun cover$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/lang/String;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V protected final fun createText (Ljava/lang/String;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)Lorg/jetbrains/dokka/pages/ContentText; + public final fun descriptionList (Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;)V + public static synthetic fun descriptionList$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;Lkotlin/jvm/functions/Function1;ILjava/lang/Object;)V public final fun divergentGroup (Lorg/jetbrains/dokka/pages/ContentDivergentGroup$GroupID;Ljava/util/Set;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ZLkotlin/jvm/functions/Function1;)V public static synthetic fun divergentGroup$default (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/pages/ContentDivergentGroup$GroupID;Ljava/util/Set;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ZLkotlin/jvm/functions/Function1;ILjava/lang/Object;)V public final fun firstParagraphComment (Lorg/jetbrains/dokka/model/doc/DocTag;Lorg/jetbrains/dokka/pages/Kind;Ljava/util/Set;Ljava/util/Set;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)V diff --git a/plugins/base/base-test-utils/api/base-test-utils.api b/plugins/base/base-test-utils/api/base-test-utils.api index c822d16bfd..d3db4866b6 100644 --- a/plugins/base/base-test-utils/api/base-test-utils.api +++ b/plugins/base/base-test-utils/api/base-test-utils.api @@ -108,10 +108,22 @@ public final class utils/Br : utils/Tag { public static final field INSTANCE Lutils/Br; } +public final class utils/Dd : utils/Tag { + public fun ([Ljava/lang/Object;)V +} + public final class utils/Div : utils/Tag { public fun ([Ljava/lang/Object;)V } +public final class utils/Dl : utils/Tag { + public fun ([Ljava/lang/Object;)V +} + +public final class utils/Dt : utils/Tag { + public fun ([Ljava/lang/Object;)V +} + public final class utils/I : utils/Tag { public fun ([Ljava/lang/Object;)V } diff --git a/plugins/base/base-test-utils/src/main/kotlin/renderers/JsoupUtils.kt b/plugins/base/base-test-utils/src/main/kotlin/renderers/JsoupUtils.kt index 47c9608a7a..a4dadca4a5 100644 --- a/plugins/base/base-test-utils/src/main/kotlin/renderers/JsoupUtils.kt +++ b/plugins/base/base-test-utils/src/main/kotlin/renderers/JsoupUtils.kt @@ -29,6 +29,9 @@ class A(vararg matchers: Any) : Tag("a", *matchers) class B(vararg matchers: Any) : Tag("b", *matchers) class I(vararg matchers: Any) : Tag("i", *matchers) class STRIKE(vararg matchers: Any) : Tag("strike", *matchers) +class Dl(vararg matchers: Any) : Tag("dl", *matchers) +class Dt(vararg matchers: Any) : Tag("dt", *matchers) +class Dd(vararg matchers: Any) : Tag("dd", *matchers) object Wbr : Tag("wbr") object Br : Tag("br") private fun Any.accepts(n: Node, ignoreSpan:Boolean = true) { diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt index b61d513ad9..304b96fa72 100644 --- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt +++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt @@ -8,7 +8,6 @@ import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.base.DokkaBaseConfiguration.Companion.defaultFooterMessage import org.jetbrains.dokka.base.renderers.* import org.jetbrains.dokka.base.renderers.html.command.consumers.ImmediateResolutionTagConsumer -import org.jetbrains.dokka.base.renderers.pageId import org.jetbrains.dokka.base.resolvers.anchors.SymbolAnchorHint import org.jetbrains.dokka.base.resolvers.local.DokkaBaseLocationProvider import org.jetbrains.dokka.base.templating.* @@ -295,8 +294,31 @@ open class HtmlRenderer( node: ContentList, pageContext: ContentPage, sourceSetRestriction: Set? - ) = if (node.ordered) ol { buildListItems(node.children, pageContext, sourceSetRestriction) } - else ul { buildListItems(node.children, pageContext, sourceSetRestriction) } + ) = if (node.ordered) { + ol { buildListItems(node.children, pageContext, sourceSetRestriction) } + } else if (node.hasStyle(ListStyle.DescriptionList)) { + dl { buildListItems(node.children, pageContext, sourceSetRestriction) } + } else { + ul { buildListItems(node.children, pageContext, sourceSetRestriction) } + } + + open fun DL.buildListItems( + items: List, + pageContext: ContentPage, + sourceSetRestriction: Set? = null + ) { + items.forEach { + when { + it.hasStyle(ListStyle.DescriptionTerm) -> dt { + it.build(this@buildListItems, pageContext, sourceSetRestriction) + } + it.hasStyle(ListStyle.DescriptionDetails) -> dd { + it.build(this@buildListItems, pageContext, sourceSetRestriction) + } + else -> it.build(this, pageContext, sourceSetRestriction) + } + } + } open fun OL.buildListItems( items: List, diff --git a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt index 8c2e1c9900..2b4317c593 100644 --- a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt +++ b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt @@ -4,10 +4,10 @@ import org.intellij.markdown.MarkdownElementTypes import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet import org.jetbrains.dokka.model.doc.* import org.jetbrains.dokka.model.properties.PropertyContainer +import org.jetbrains.dokka.model.properties.plus import org.jetbrains.dokka.model.toDisplaySourceSets import org.jetbrains.dokka.pages.* import org.jetbrains.kotlin.utils.addToStdlib.firstIsInstanceOrNull -import org.jetbrains.dokka.model.properties.plus open class DocTagToContentConverter : CommentsToContentConverter { override fun buildContent( @@ -39,14 +39,14 @@ open class DocTagToContentConverter : CommentsToContentConverter { ) ) - fun buildList(ordered: Boolean, start: Int = 1) = + fun buildList(ordered: Boolean, newStyles: Set