Gives text presentation for `SinceKotlin` and hides it from rendering. Hides `Deprecated`. #944

4 files changed, 117 insertions, 6 deletions

diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt
index 46c92c15..9a04e729 100644
--- a/plugins/base/src/main/kotlin/DokkaBase.kt
+++ b/plugins/base/src/main/kotlin/DokkaBase.kt
@@ -15,6 +15,7 @@ import org.jetbrains.dokka.base.transformers.documentables.DocumentableVisibilit
 import org.jetbrains.dokka.base.transformers.documentables.ModuleAndPackageDocumentationTransformer
 import org.jetbrains.dokka.base.transformers.documentables.ReportUndocumentedTransformer
 import org.jetbrains.dokka.base.transformers.pages.annotations.DeprecatedStrikethroughTransformer
+import org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinTransformer
 import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter
 import org.jetbrains.dokka.base.transformers.pages.comments.DocTagToContentConverter
 import org.jetbrains.dokka.base.transformers.pages.merger.FallbackPageMergerStrategy
@@ -65,6 +66,10 @@ class DokkaBase : DokkaPlugin() {
         }
     }
 
+    val sinceKotlinTransformer by extending {
+        CoreExtensions.documentableTransformer providing ::SinceKotlinTransformer
+    }
+
     val inheritorsExtractor by extending {
         CoreExtensions.documentableTransformer with InheritorsExtractorTransformer()
     }
diff --git a/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt b/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt
index c8ff3fac..b312c8f0 100644
--- a/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt
+++ b/plugins/base/src/main/kotlin/signatures/KotlinSignatureUtils.kt
@@ -1,7 +1,9 @@
 package org.jetbrains.dokka.base.signatures
 
 import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder
+import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.AdditionalModifiers
+import org.jetbrains.dokka.model.Annotations
 import org.jetbrains.dokka.model.Documentable
 import org.jetbrains.dokka.model.ExtraModifiers
 import org.jetbrains.dokka.model.properties.WithExtraProperties
@@ -11,13 +13,17 @@ object KotlinSignatureUtils : JvmSignatureUtils {
     private val strategy = OnlyOnce
     private val listBrackets = Pair('[', ']')
     private val classExtension = "::class"
+    val ignoredAnnotations = setOf(
+        Annotations.Annotation(DRI("kotlin", "SinceKotlin"), emptyMap()),
+        Annotations.Annotation(DRI("kotlin", "Deprecated"), emptyMap())
+    )
 
 
     override fun PageContentBuilder.DocumentableContentBuilder.annotationsBlock(d: Documentable) =
-        annotationsBlockWithIgnored(d, emptySet(), strategy, listBrackets, classExtension)
+        annotationsBlockWithIgnored(d, ignoredAnnotations, strategy, listBrackets, classExtension)
 
     override fun PageContentBuilder.DocumentableContentBuilder.annotationsInline(d: Documentable) =
-        annotationsInlineWithIgnored(d, emptySet(), strategy, listBrackets, classExtension)
+        annotationsInlineWithIgnored(d, ignoredAnnotations, strategy, listBrackets, classExtension)
 
     override fun <T : Documentable> WithExtraProperties<T>.modifiers() =
         extra[AdditionalModifiers]?.content?.entries?.map {
diff --git a/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt
new file mode 100644
index 00000000..7914e88f
--- /dev/null
+++ b/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt
@@ -0,0 +1,82 @@
+package org.jetbrains.dokka.base.transformers.pages.annotations
+
+import org.jetbrains.dokka.links.DRI
+import org.jetbrains.dokka.model.*
+import org.jetbrains.dokka.model.doc.CustomTagWrapper
+import org.jetbrains.dokka.model.doc.Text
+import org.jetbrains.dokka.model.properties.WithExtraProperties
+import org.jetbrains.dokka.plugability.DokkaContext
+import org.jetbrains.dokka.transformers.documentation.DocumentableTransformer
+import org.jetbrains.kotlin.utils.addToStdlib.safeAs
+
+class SinceKotlinTransformer(val context: DokkaContext) : DocumentableTransformer {
+
+    override fun invoke(original: DModule, context: DokkaContext) = original.transform() as DModule
+
+    private fun <T : Documentable> T.transform(): Documentable =
+        when (this) {
+            is DModule -> copy(
+                packages = packages.map { it.transform() as DPackage }
+            )
+            is DPackage -> copy(
+                classlikes = classlikes.map { it.transform() as DClasslike },
+                functions = functions.map { it.transform() as DFunction },
+                properties = properties.map { it.transform() as DProperty }
+            )
+            is DClass -> copy(
+                documentation = appendSinceKotlin(),
+                classlikes = classlikes.map { it.transform() as DClasslike },
+                functions = functions.map { it.transform() as DFunction },
+                properties = properties.map { it.transform() as DProperty }
+            )
+            is DEnum -> copy(
+                documentation = appendSinceKotlin(),
+                classlikes = classlikes.map { it.transform() as DClasslike },
+                functions = functions.map { it.transform() as DFunction },
+                properties = properties.map { it.transform() as DProperty }
+            )
+            is DInterface -> copy(
+                documentation = appendSinceKotlin(),
+                classlikes = classlikes.map { it.transform() as DClasslike },
+                functions = functions.map { it.transform() as DFunction },
+                properties = properties.map { it.transform() as DProperty }
+            )
+            is DObject -> copy(
+                documentation = appendSinceKotlin(),
+                classlikes = classlikes.map { it.transform() as DClasslike },
+                functions = functions.map { it.transform() as DFunction },
+                properties = properties.map { it.transform() as DProperty }
+            )
+            is DAnnotation -> copy(
+                documentation = appendSinceKotlin(),
+                classlikes = classlikes.map { it.transform() as DClasslike },
+                functions = functions.map { it.transform() as DFunction },
+                properties = properties.map { it.transform() as DProperty }
+            )
+            is DFunction -> copy(
+                documentation = appendSinceKotlin()
+            )
+            is DProperty -> copy(
+                documentation = appendSinceKotlin()
+            )
+            is DParameter -> copy(
+                documentation = appendSinceKotlin()
+            )
+            else -> this.also { context.logger.warn("Unrecognized documentable $this while SinceKotlin transformation") }
+        }
+
+    private fun Documentable.appendSinceKotlin() =
+        sourceSets.fold(documentation) { acc, sourceSet ->
+            safeAs<WithExtraProperties<Documentable>>()?.extra?.get(Annotations)?.content?.get(sourceSet)?.find {
+                it.dri == DRI("kotlin", "SinceKotlin")
+            }?.params?.get("version").safeAs<StringValue>()?.value?.let { version ->
+                acc.mapValues {
+                    if (it.key == sourceSet) it.value.copy(
+                        it.value.children + listOf(
+                            CustomTagWrapper(Text(version.dropWhile { it == '"' }.dropLastWhile { it == '"' }), "Since Kotlin")
+                        )
+                    ) else it.value
+                }
+            } ?: acc
+        }
+}
\ No newline at end of file
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
index a6dd337a..8c7707f8 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
@@ -247,6 +247,8 @@ open class DefaultPageCreator(
                     }
                 }
             }
+
+            contentForSinceKotlin(d)
         }.children
     }
 
@@ -352,9 +354,9 @@ open class DefaultPageCreator(
         }.children
     }
 
-    protected open fun DocumentableContentBuilder.contentForBrief(content: Documentable) {
-        content.sourceSets.forEach { sourceSet ->
-            content.documentation[sourceSet]?.children?.firstOrNull()?.root?.let {
+    protected open fun DocumentableContentBuilder.contentForBrief(documentable: Documentable) {
+        documentable.sourceSets.forEach { sourceSet ->
+            documentable.documentation[sourceSet]?.children?.firstOrNull()?.root?.let {
                 group(sourceSets = setOf(sourceSet), kind = ContentKind.BriefComment) {
                     comment(it)
                 }
@@ -362,6 +364,21 @@ open class DefaultPageCreator(
         }
     }
 
+    protected open fun DocumentableContentBuilder.contentForSinceKotlin(documentable: Documentable) {
+        documentable.documentation.mapValues {
+            it.value.children.find { it is CustomTagWrapper && it.name == "Since Kotlin" } as CustomTagWrapper?
+        }.run {
+            documentable.sourceSets.forEach { sourceSet ->
+                this[sourceSet]?.also { tag ->
+                    group(sourceSets = setOf(sourceSet)) {
+                        header(4, (tag as CustomTagWrapper).name)
+                        comment(tag.root)
+                    }
+                }
+            }
+        }
+    }
+
     protected open fun contentForFunction(f: DFunction) = contentForMember(f)
     protected open fun contentForTypeAlias(t: DTypeAlias) = contentForMember(t)
     protected open fun contentForMember(d: Documentable) = contentBuilder.contentFor(d) {
@@ -385,7 +402,7 @@ open class DefaultPageCreator(
         name: String,
         collection: Collection<Documentable>,
         kind: ContentKind,
-        extra: PropertyContainer<ContentNode> = mainExtra,
+        extra: PropertyContainer<ContentNode> = mainExtra
     ) {
         if (collection.any()) {
             header(2, name)
@@ -405,6 +422,7 @@ open class DefaultPageCreator(
                                 instance(setOf(it.dri), it.sourceSets.toSet()) {
                                     before {
                                         contentForBrief(it)
+                                        contentForSinceKotlin(it)
                                     }
                                     divergent {
                                         group {