Custom doctag extension (#2343)

* Add an extension point for rendering custom doc tags

* Iterate over documentable sourcesets when building custom tags

* Extract a nested custom tags brief block into a separate method

* Filter out tag content providers and make since kotlin brief a one-liner

* Add padding to "Since Kotlin" block in brief description

2 files changed, 93 insertions, 0 deletions

diff --git a/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt b/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt
new file mode 100644
index 00000000..e818ef1d
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt
@@ -0,0 +1,59 @@
+package org.jetbrains.dokka.base.transformers.pages.tags
+
+import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
+import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder
+import org.jetbrains.dokka.model.doc.CustomTagWrapper
+import org.jetbrains.dokka.model.doc.DocTag
+
+/**
+ * Provides an ability to render custom doc tags
+ *
+ * Custom tags can be generated during build, for instance via transformers from converting an annotation
+ * (such as in [org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinTransformer])
+ *
+ * Also, custom tags can come from the kdoc itself, where "custom" is defined as unknown to the compiler/spec.
+ * `@property` and `@throws` are not custom tags - they are defined by the spec and have special meaning
+ * and separate blocks on the documentation page, it's clear how to render it. Whereas `@usesMathJax` is
+ * a custom tag - it's application/plugin specific and is not handled by dokka by default.
+ *
+ * Using this provider, we can map custom tags  (such as `@usesMathJax`) and generate content for it that
+ * will be displayed on the pages.
+ */
+interface CustomTagContentProvider {
+
+    /**
+     * Whether this content provider supports given [CustomTagWrapper].
+     *
+     * Tags can be filtered out either by name or by nested [DocTag] type
+     */
+    fun isApplicable(customTag: CustomTagWrapper): Boolean
+
+    /**
+     * Full blown content description, most likely to be on a separate page
+     * dedicated to just one element (i.e one class/function), so any
+     * amount of detail should be fine.
+     */
+    fun DocumentableContentBuilder.contentForDescription(
+        sourceSet: DokkaSourceSet,
+        customTag: CustomTagWrapper
+    ) {}
+
+    /**
+     * Brief comment section, usually displayed as a summary/preview.
+     *
+     * For instance, when listing all functions of a class on one page,
+     * it'll be too much to display complete documentation for each function.
+     * Instead, a small brief is shown for each one (i.e the first paragraph
+     * or some other important information) - the user can go to the dedicated
+     * page for more details if they find the brief interesting.
+     *
+     * Tag-wise, it would make sense to include `Since Kotlin`, since it's
+     * important information for the users of stdlib. It would make little
+     * sense to include `@usesMathjax` here, as this information seems
+     * to be more specific and detailed than is needed for a brief.
+     */
+    fun DocumentableContentBuilder.contentForBrief(
+        sourceSet: DokkaSourceSet,
+        customTag: CustomTagWrapper
+    ) {}
+}
diff --git a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt
new file mode 100644
index 00000000..c9010421
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt
@@ -0,0 +1,34 @@
+package org.jetbrains.dokka.base.transformers.pages.tags
+
+import org.jetbrains.dokka.DokkaConfiguration
+import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder
+import org.jetbrains.dokka.model.doc.CustomTagWrapper
+import org.jetbrains.dokka.pages.ContentKind
+import org.jetbrains.dokka.pages.TextStyle
+
+object SinceKotlinTagContentProvider : CustomTagContentProvider {
+
+    private const val SINCE_KOTLIN_TAG_NAME = "Since Kotlin"
+
+    override fun isApplicable(customTag: CustomTagWrapper) = customTag.name == SINCE_KOTLIN_TAG_NAME
+
+    override fun DocumentableContentBuilder.contentForDescription(
+        sourceSet: DokkaConfiguration.DokkaSourceSet,
+        customTag: CustomTagWrapper
+    ) {
+        group(sourceSets = setOf(sourceSet), kind = ContentKind.Comment, styles = setOf(TextStyle.Block)) {
+            header(4, customTag.name)
+            comment(customTag.root)
+        }
+    }
+
+    override fun DocumentableContentBuilder.contentForBrief(
+        sourceSet: DokkaConfiguration.DokkaSourceSet,
+        customTag: CustomTagWrapper
+    ) {
+        group(sourceSets = setOf(sourceSet), styles = setOf(TextStyle.InlineComment)) {
+            text(customTag.name + " ", styles = setOf(TextStyle.Bold))
+            comment(customTag.root, styles = emptySet())
+        }
+    }
+}
\ No newline at end of file