From cc89f0b74a870303c854fcb892d469d4c8fb17a8 Mon Sep 17 00:00:00 2001 From: Andrzej Ratajczak Date: Tue, 9 Jun 2020 16:31:58 +0200 Subject: Gives text presentation for `SinceKotlin` and hides it from rendering. Hides `Deprecated`. #944 --- plugins/base/src/main/kotlin/DokkaBase.kt | 5 ++ .../main/kotlin/signatures/KotlinSignatureUtils.kt | 10 ++- .../pages/annotations/SinceKotlinTransformer.kt | 82 ++++++++++++++++++++++ .../documentables/DefaultPageCreator.kt | 26 +++++-- 4 files changed, 117 insertions(+), 6 deletions(-) create mode 100644 plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt (limited to 'plugins/base/src/main/kotlin') 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 WithExtraProperties.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.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>()?.extra?.get(Annotations)?.content?.get(sourceSet)?.find { + it.dri == DRI("kotlin", "SinceKotlin") + }?.params?.get("version").safeAs()?.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, kind: ContentKind, - extra: PropertyContainer = mainExtra, + extra: PropertyContainer = 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 { -- cgit