From b833b71590fb0931b3f1e0c9c3ff6aba8a3e4679 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 3 Feb 2022 20:23:14 +0300 Subject: [PATCH 1/8] Add an extension point for rendering custom doc tags --- plugins/base/api/base.api | 23 ++++++++- plugins/base/src/main/kotlin/DokkaBase.kt | 7 +++ .../pages/tags/CustomTagContentProvider.kt | 51 +++++++++++++++++++ .../tags/SinceKotlinTagContentProvider.kt | 38 ++++++++++++++ .../DefaultDocumentableToPageTranslator.kt | 14 +++-- .../documentables/DefaultPageCreator.kt | 49 +++++++++++------- plugins/kotlin-as-java/api/kotlin-as-java.api | 2 +- ...otlinAsJavaDocumentableToPageTranslator.kt | 14 +++-- .../translators/KotlinAsJavaPageCreator.kt | 12 ++++- 9 files changed, 176 insertions(+), 34 deletions(-) create mode 100644 plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt create mode 100644 plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 488d2d8d65..121ef45f49 100644 --- a/plugins/base/api/base.api +++ b/plugins/base/api/base.api @@ -5,6 +5,7 @@ public final class org/jetbrains/dokka/base/DokkaBase : org/jetbrains/dokka/plug public final fun getBaseSearchbarDataInstaller ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getCommentsToContentConverter ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getCustomResourceInstaller ()Lorg/jetbrains/dokka/plugability/Extension; + public final fun getCustomTagContentProvider ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; public final fun getDefaultExternalClasslikesTranslator ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDefaultExternalDocumentablesProvider ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getDefaultKotlinAnalysis ()Lorg/jetbrains/dokka/plugability/Extension; @@ -52,6 +53,7 @@ public final class org/jetbrains/dokka/base/DokkaBase : org/jetbrains/dokka/plug public final fun getSameMethodNameMerger ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getScriptsInstaller ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getSignatureProvider ()Lorg/jetbrains/dokka/plugability/ExtensionPoint; + public final fun getSinceKotlinTagContentProvider ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getSinceKotlinTransformer ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getSingleGeneration ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getSourceLinksTransformer ()Lorg/jetbrains/dokka/plugability/Extension; @@ -1267,6 +1269,22 @@ public final class org/jetbrains/dokka/base/transformers/pages/sourcelinks/Sourc public static final fun hasTabbedContent (Lorg/jetbrains/dokka/pages/ContentGroup;)Z } +public abstract interface class org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider { + public abstract fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public abstract fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V +} + +public final class org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider$DefaultImpls { + public static fun contentForBrief (Lorg/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider;Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public static fun contentForDescription (Lorg/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider;Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V +} + +public final class org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider : org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider { + public static final field INSTANCE Lorg/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider; + public fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V +} + public final class org/jetbrains/dokka/base/translators/descriptors/DRIWithPlatformInfo { public fun (Lorg/jetbrains/dokka/links/DRI;Ljava/util/Map;)V public final fun component1 ()Lorg/jetbrains/dokka/links/DRI; @@ -1319,7 +1337,8 @@ public final class org/jetbrains/dokka/base/translators/documentables/DefaultDoc } public class org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator { - public fun (Lorg/jetbrains/dokka/base/DokkaBaseConfiguration;Lorg/jetbrains/dokka/base/transformers/pages/comments/CommentsToContentConverter;Lorg/jetbrains/dokka/base/signatures/SignatureProvider;Lorg/jetbrains/dokka/utilities/DokkaLogger;)V + public fun (Lorg/jetbrains/dokka/base/DokkaBaseConfiguration;Lorg/jetbrains/dokka/base/transformers/pages/comments/CommentsToContentConverter;Lorg/jetbrains/dokka/base/signatures/SignatureProvider;Lorg/jetbrains/dokka/utilities/DokkaLogger;Ljava/util/List;)V + public synthetic fun (Lorg/jetbrains/dokka/base/DokkaBaseConfiguration;Lorg/jetbrains/dokka/base/transformers/pages/comments/CommentsToContentConverter;Lorg/jetbrains/dokka/base/signatures/SignatureProvider;Lorg/jetbrains/dokka/utilities/DokkaLogger;Ljava/util/List;ILkotlin/jvm/internal/DefaultConstructorMarker;)V protected fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/Documentable;)V protected fun contentForClasslike (Lorg/jetbrains/dokka/model/DClasslike;)Lorg/jetbrains/dokka/pages/ContentGroup; protected fun contentForComments (Lorg/jetbrains/dokka/model/Documentable;Z)Ljava/util/List; @@ -1332,10 +1351,10 @@ public class org/jetbrains/dokka/base/translators/documentables/DefaultPageCreat protected fun contentForPackage (Lorg/jetbrains/dokka/model/DPackage;)Lorg/jetbrains/dokka/pages/ContentGroup; protected fun contentForProperty (Lorg/jetbrains/dokka/model/DProperty;)Lorg/jetbrains/dokka/pages/ContentGroup; protected fun contentForScope (Lorg/jetbrains/dokka/model/WithScope;Lorg/jetbrains/dokka/links/DRI;Ljava/util/Set;)Lorg/jetbrains/dokka/pages/ContentGroup; - protected fun contentForSinceKotlin (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/model/Documentable;)V protected fun divergentBlock (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/lang/String;Ljava/util/Collection;Lorg/jetbrains/dokka/pages/ContentKind;Lorg/jetbrains/dokka/model/properties/PropertyContainer;)V public static synthetic fun divergentBlock$default (Lorg/jetbrains/dokka/base/translators/documentables/DefaultPageCreator;Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Ljava/lang/String;Ljava/util/Collection;Lorg/jetbrains/dokka/pages/ContentKind;Lorg/jetbrains/dokka/model/properties/PropertyContainer;ILjava/lang/Object;)V protected fun getContentBuilder ()Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder; + public final fun getCustomTagContentProviders ()Ljava/util/List; public final fun getLogger ()Lorg/jetbrains/dokka/utilities/DokkaLogger; protected final fun getSeparateInheritedMembers ()Z public fun pageForClasslike (Lorg/jetbrains/dokka/model/DClasslike;)Lorg/jetbrains/dokka/pages/ClasslikePageNode; diff --git a/plugins/base/src/main/kotlin/DokkaBase.kt b/plugins/base/src/main/kotlin/DokkaBase.kt index a26f6dcdad..0443b136af 100644 --- a/plugins/base/src/main/kotlin/DokkaBase.kt +++ b/plugins/base/src/main/kotlin/DokkaBase.kt @@ -29,6 +29,8 @@ import org.jetbrains.dokka.base.translators.documentables.DefaultDocumentableToP import org.jetbrains.dokka.base.translators.psi.DefaultPsiToDocumentableTranslator import org.jetbrains.dokka.base.generation.SingleModuleGeneration import org.jetbrains.dokka.base.renderers.html.command.consumers.ReplaceVersionsConsumer +import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider +import org.jetbrains.dokka.base.transformers.pages.tags.SinceKotlinTagContentProvider import org.jetbrains.dokka.base.translators.descriptors.DefaultExternalDocumentablesProvider import org.jetbrains.dokka.base.translators.descriptors.ExternalClasslikesTranslator import org.jetbrains.dokka.base.translators.descriptors.ExternalDocumentablesProvider @@ -41,6 +43,7 @@ class DokkaBase : DokkaPlugin() { val preMergeDocumentableTransformer by extensionPoint() val pageMergerStrategy by extensionPoint() val commentsToContentConverter by extensionPoint() + val customTagContentProvider by extensionPoint() val signatureProvider by extensionPoint() val locationProviderFactory by extensionPoint() val externalLocationProviderFactory by extensionPoint() @@ -151,6 +154,10 @@ class DokkaBase : DokkaPlugin() { commentsToContentConverter with DocTagToContentConverter() } + val sinceKotlinTagContentProvider by extending { + customTagContentProvider with SinceKotlinTagContentProvider + } + val pageMerger by extending { CoreExtensions.pageTransformer providing ::PageMerger } 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 0000000000..b167ffa417 --- /dev/null +++ b/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt @@ -0,0 +1,51 @@ +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 + +/** + * 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 { + + /** + * 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 0000000000..5aa3574309 --- /dev/null +++ b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt @@ -0,0 +1,38 @@ +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 val TAG_NAME = "Since Kotlin" + + override fun DocumentableContentBuilder.contentForDescription( + sourceSet: DokkaConfiguration.DokkaSourceSet, + customTag: CustomTagWrapper + ) { + sinceKotlinBlock(sourceSet, customTag) + } + + override fun DocumentableContentBuilder.contentForBrief( + sourceSet: DokkaConfiguration.DokkaSourceSet, + customTag: CustomTagWrapper + ) { + sinceKotlinBlock(sourceSet, customTag) + } + + private fun DocumentableContentBuilder.sinceKotlinBlock( + sourceSet: DokkaConfiguration.DokkaSourceSet, + customTag: CustomTagWrapper + ) { + if (customTag.name == TAG_NAME) { + group(sourceSets = setOf(sourceSet), kind = ContentKind.Comment, styles = setOf(TextStyle.Block)) { + header(4, customTag.name) + comment(customTag.root) + } + } + } +} \ No newline at end of file diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt index 186472075b..a385e0e4fa 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt @@ -4,10 +4,7 @@ import org.jetbrains.dokka.base.DokkaBase import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.model.DModule import org.jetbrains.dokka.pages.ModulePageNode -import org.jetbrains.dokka.plugability.configuration -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.plugin -import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.plugability.* import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator class DefaultDocumentableToPageTranslator( @@ -16,8 +13,15 @@ class DefaultDocumentableToPageTranslator( private val configuration = configuration(context) private val commentsToContentConverter = context.plugin().querySingle { commentsToContentConverter } private val signatureProvider = context.plugin().querySingle { signatureProvider } + private val customTagContentProviders = context.plugin().query { customTagContentProvider } private val logger = context.logger override fun invoke(module: DModule): ModulePageNode = - DefaultPageCreator(configuration, commentsToContentConverter, signatureProvider, logger).pageForModule(module) + DefaultPageCreator( + configuration, + commentsToContentConverter, + signatureProvider, + logger, + customTagContentProviders + ).pageForModule(module) } \ 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 c16996a056..0c4f11fd3e 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -19,6 +19,7 @@ import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet import org.jetbrains.dokka.base.DokkaBaseConfiguration import org.jetbrains.dokka.base.resolvers.anchors.SymbolAnchorHint import org.jetbrains.dokka.base.transformers.documentables.ClashingDriIdentifier +import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider private typealias GroupedTags = Map, List>> @@ -29,7 +30,8 @@ open class DefaultPageCreator( configuration: DokkaBaseConfiguration?, commentsToContentConverter: CommentsToContentConverter, signatureProvider: SignatureProvider, - val logger: DokkaLogger + val logger: DokkaLogger, + val customTagContentProviders: List = emptyList() ) { protected open val contentBuilder = PageContentBuilder(commentsToContentConverter, signatureProvider, logger) @@ -341,6 +343,21 @@ open class DefaultPageCreator( } } + val customTags = d.customTags + if (customTags.isNotEmpty()) { + group(styles = setOf(TextStyle.Block)) { + customTags.forEach { (tagName, sourceSetDependent) -> + sourceSetDependent.forEach { (sourceSet, tag) -> + customTagContentProviders.forEach { provider -> + with(provider) { + contentForDescription(sourceSet, tag) + } + } + } + } + } + } + val unnamedTags = tags.filterNot { (k, _) -> k.isSubclassOf(NamedTagWrapper::class) || k in specialTags } .values.flatten().groupBy { it.first }.mapValues { it.value.map { it.second } } if (unnamedTags.isNotEmpty()) { @@ -357,8 +374,6 @@ open class DefaultPageCreator( } } } - - contentForSinceKotlin(d) }.children } @@ -560,21 +575,6 @@ open class DefaultPageCreator( } ?: firstParagraphComment(tag.root) } - 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), kind = ContentKind.Comment, styles = setOf(TextStyle.Block)) { - header(4, tag.name) - comment(tag.root) - } - } - } - } - } - protected open fun contentForFunction(f: DFunction) = contentForMember(f) protected open fun contentForProperty(p: DProperty) = contentForMember(p) @@ -681,7 +681,15 @@ open class DefaultPageCreator( } after(extra = PropertyContainer.empty()) { contentForBrief(it) - contentForSinceKotlin(it) + it.customTags.forEach { (tagName, sourceSetDependent) -> + sourceSetDependent.forEach { (sourceSet, tag) -> + customTagContentProviders.forEach { provider -> + with(provider) { + contentForBrief(sourceSet, tag) + } + } + } + } } } } @@ -706,6 +714,9 @@ open class DefaultPageCreator( private val Documentable.descriptions: SourceSetDependent get() = groupedTags.withTypeUnnamed() + private val Documentable.customTags: Map> + get() = groupedTags.withTypeNamed() + private val Documentable.hasSeparatePage: Boolean get() = this !is DTypeAlias diff --git a/plugins/kotlin-as-java/api/kotlin-as-java.api b/plugins/kotlin-as-java/api/kotlin-as-java.api index f941582ecd..92a8189041 100644 --- a/plugins/kotlin-as-java/api/kotlin-as-java.api +++ b/plugins/kotlin-as-java/api/kotlin-as-java.api @@ -82,7 +82,7 @@ public final class org/jetbrains/dokka/kotlinAsJava/translators/KotlinAsJavaDocu } public final class org/jetbrains/dokka/kotlinAsJava/translators/KotlinAsJavaPageCreator : org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator { - public fun (Lorg/jetbrains/dokka/base/DokkaBaseConfiguration;Lorg/jetbrains/dokka/base/transformers/pages/comments/CommentsToContentConverter;Lorg/jetbrains/dokka/base/signatures/SignatureProvider;Lorg/jetbrains/dokka/utilities/DokkaLogger;)V + public fun (Lorg/jetbrains/dokka/base/DokkaBaseConfiguration;Lorg/jetbrains/dokka/base/transformers/pages/comments/CommentsToContentConverter;Lorg/jetbrains/dokka/base/signatures/SignatureProvider;Lorg/jetbrains/dokka/utilities/DokkaLogger;Ljava/util/List;)V public fun pageForProperty (Lorg/jetbrains/dokka/model/DProperty;)Lorg/jetbrains/dokka/pages/MemberPageNode; } diff --git a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt index 0f7d74b62e..f1aae2dc7a 100644 --- a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt +++ b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaDocumentableToPageTranslator.kt @@ -8,18 +8,22 @@ import org.jetbrains.dokka.DokkaConfiguration import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator import org.jetbrains.dokka.model.DModule import org.jetbrains.dokka.pages.ModulePageNode -import org.jetbrains.dokka.plugability.configuration -import org.jetbrains.dokka.plugability.DokkaContext -import org.jetbrains.dokka.plugability.plugin -import org.jetbrains.dokka.plugability.querySingle +import org.jetbrains.dokka.plugability.* import org.jetbrains.dokka.utilities.DokkaLogger class KotlinAsJavaDocumentableToPageTranslator(context: DokkaContext) : DocumentableToPageTranslator { private val configuration = configuration(context) private val commentsToContentConverter = context.plugin().querySingle { commentsToContentConverter } private val signatureProvider = context.plugin().querySingle { signatureProvider } + private val customTagContentProviders = context.plugin().query { customTagContentProvider } private val logger: DokkaLogger = context.logger override fun invoke(module: DModule): ModulePageNode = - KotlinAsJavaPageCreator(configuration, commentsToContentConverter, signatureProvider, logger).pageForModule(module) + KotlinAsJavaPageCreator( + configuration, + commentsToContentConverter, + signatureProvider, + logger, + customTagContentProviders + ).pageForModule(module) } \ No newline at end of file diff --git a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt index b2cf624651..ef0751536d 100644 --- a/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt +++ b/plugins/kotlin-as-java/src/main/kotlin/translators/KotlinAsJavaPageCreator.kt @@ -5,6 +5,7 @@ import org.jetbrains.dokka.base.signatures.SignatureProvider import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter import org.jetbrains.dokka.base.translators.documentables.DefaultPageCreator import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider import org.jetbrains.dokka.model.DProperty import org.jetbrains.dokka.pages.MemberPageNode import org.jetbrains.dokka.utilities.DokkaLogger @@ -13,7 +14,14 @@ class KotlinAsJavaPageCreator( configuration: DokkaBaseConfiguration?, commentsToContentConverter: CommentsToContentConverter, signatureProvider: SignatureProvider, - logger: DokkaLogger -) : DefaultPageCreator(configuration, commentsToContentConverter, signatureProvider, logger) { + logger: DokkaLogger, + customTagContentProviders: List +) : DefaultPageCreator( + configuration, + commentsToContentConverter, + signatureProvider, + logger, + customTagContentProviders = customTagContentProviders +) { override fun pageForProperty(p: DProperty): MemberPageNode? = null } \ No newline at end of file From dc752989295b7a8831c378973f4daa15d985d5f1 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 3 Feb 2022 20:24:13 +0300 Subject: [PATCH 2/8] Utilize the new custom doc tag extension API for mathjax --- plugins/mathjax/api/mathjax.api | 7 +++++++ plugins/mathjax/build.gradle.kts | 3 ++- .../mathjax/src/main/kotlin/MathjaxPlugin.kt | 21 +++++++++++++++++++ 3 files changed, 30 insertions(+), 1 deletion(-) diff --git a/plugins/mathjax/api/mathjax.api b/plugins/mathjax/api/mathjax.api index 47612ecb78..a3a15839a0 100644 --- a/plugins/mathjax/api/mathjax.api +++ b/plugins/mathjax/api/mathjax.api @@ -1,8 +1,15 @@ public final class org/jetbrains/dokka/mathjax/MathjaxPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { public fun ()V + public final fun getMathjaxTagContentProvider ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getTransformer ()Lorg/jetbrains/dokka/plugability/Extension; } +public final class org/jetbrains/dokka/mathjax/MathjaxTagContentProvider : org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider { + public static final field INSTANCE Lorg/jetbrains/dokka/mathjax/MathjaxTagContentProvider; + public fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V +} + public final class org/jetbrains/dokka/mathjax/MathjaxTransformer : org/jetbrains/dokka/transformers/pages/PageTransformer { public static final field INSTANCE Lorg/jetbrains/dokka/mathjax/MathjaxTransformer; public fun invoke (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode; diff --git a/plugins/mathjax/build.gradle.kts b/plugins/mathjax/build.gradle.kts index 50e838a8cd..0b69a03827 100644 --- a/plugins/mathjax/build.gradle.kts +++ b/plugins/mathjax/build.gradle.kts @@ -1,9 +1,10 @@ import org.jetbrains.registerDokkaArtifactPublication dependencies { + implementation(project(":plugins:base")) + val jsoup_version: String by project testImplementation("org.jsoup:jsoup:$jsoup_version") - testImplementation(project(":plugins:base")) testImplementation(project(":plugins:base:base-test-utils")) testImplementation(project(":core:content-matcher-test-utils")) testImplementation(kotlin("test-junit")) diff --git a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt index 636995856c..dd8d15ee09 100644 --- a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt +++ b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt @@ -2,6 +2,10 @@ package org.jetbrains.dokka.mathjax import org.jetbrains.dokka.CoreExtensions +import org.jetbrains.dokka.DokkaConfiguration +import org.jetbrains.dokka.base.DokkaBase +import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider +import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder import org.jetbrains.dokka.model.doc.CustomTagWrapper import org.jetbrains.dokka.pages.ContentPage import org.jetbrains.dokka.pages.RootPageNode @@ -12,6 +16,12 @@ class MathjaxPlugin : DokkaPlugin() { val transformer by extending { CoreExtensions.pageTransformer with MathjaxTransformer } + + val mathjaxTagContentProvider by extending { + plugin().customTagContentProvider with MathjaxTagContentProvider order { + before(plugin().sinceKotlinTagContentProvider) + } + } } private const val ANNOTATION = "usesMathJax" @@ -29,4 +39,15 @@ object MathjaxTransformer : PageTransformer { ?.flatMap { it.children } .orEmpty() .any { (it as? CustomTagWrapper)?.name == ANNOTATION } +} + +object MathjaxTagContentProvider : CustomTagContentProvider { + override fun DocumentableContentBuilder.contentForDescription( + sourceSet: DokkaConfiguration.DokkaSourceSet, + customTag: CustomTagWrapper + ) { + if (customTag.name == ANNOTATION) { + comment(customTag.root, sourceSets = setOf(sourceSet)) + } + } } \ No newline at end of file From b0a58115940dc4cf08cc2f54e6bdc322624388f0 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 3 Feb 2022 20:43:34 +0300 Subject: [PATCH 3/8] Iterate over documentable sourcesets when building custom tags --- .../documentables/DefaultPageCreator.kt | 28 ++++++++++++------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index 0c4f11fd3e..72305b6890 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -346,11 +346,13 @@ open class DefaultPageCreator( val customTags = d.customTags if (customTags.isNotEmpty()) { group(styles = setOf(TextStyle.Block)) { - customTags.forEach { (tagName, sourceSetDependent) -> - sourceSetDependent.forEach { (sourceSet, tag) -> - customTagContentProviders.forEach { provider -> - with(provider) { - contentForDescription(sourceSet, tag) + platforms.forEach { platform -> + customTags.forEach { (tagName, sourceSetTag) -> + sourceSetTag[platform]?.let { tag -> + customTagContentProviders.forEach { provider -> + with(provider) { + contentForDescription(platform, tag) + } } } } @@ -681,11 +683,17 @@ open class DefaultPageCreator( } after(extra = PropertyContainer.empty()) { contentForBrief(it) - it.customTags.forEach { (tagName, sourceSetDependent) -> - sourceSetDependent.forEach { (sourceSet, tag) -> - customTagContentProviders.forEach { provider -> - with(provider) { - contentForBrief(sourceSet, tag) + + val customTags = it.customTags + if (customTags.isNotEmpty()) { + it.sourceSets.forEach { sourceSet -> + customTags.forEach { (tagName, sourceSetTag) -> + sourceSetTag[sourceSet]?.let { tag -> + customTagContentProviders.forEach { provider -> + with(provider) { + contentForDescription(sourceSet, tag) + } + } } } } From ac9b0a6ae4d068716bf5e291dc5f1fcbd06a5809 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 3 Feb 2022 20:48:50 +0300 Subject: [PATCH 4/8] Correct a typo --- .../main/kotlin/translators/documentables/DefaultPageCreator.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index 72305b6890..0c13a5bea2 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -691,7 +691,7 @@ open class DefaultPageCreator( sourceSetTag[sourceSet]?.let { tag -> customTagContentProviders.forEach { provider -> with(provider) { - contentForDescription(sourceSet, tag) + contentForBrief(sourceSet, tag) } } } From f89fab1fdcf022b7b6db542a600882732c6ac703 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Mon, 14 Feb 2022 12:11:03 +0300 Subject: [PATCH 5/8] Extract a nested custom tags brief block into a separate method --- .../tags/SinceKotlinTagContentProvider.kt | 2 +- .../documentables/DefaultPageCreator.kt | 32 ++++++++++--------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt index 5aa3574309..904784c08d 100644 --- a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt +++ b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt @@ -8,7 +8,7 @@ import org.jetbrains.dokka.pages.TextStyle object SinceKotlinTagContentProvider : CustomTagContentProvider { - private val TAG_NAME = "Since Kotlin" + private const val TAG_NAME = "Since Kotlin" override fun DocumentableContentBuilder.contentForDescription( sourceSet: DokkaConfiguration.DokkaSourceSet, diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index 0c13a5bea2..c6dc0b8ce0 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -683,21 +683,7 @@ open class DefaultPageCreator( } after(extra = PropertyContainer.empty()) { contentForBrief(it) - - val customTags = it.customTags - if (customTags.isNotEmpty()) { - it.sourceSets.forEach { sourceSet -> - customTags.forEach { (tagName, sourceSetTag) -> - sourceSetTag[sourceSet]?.let { tag -> - customTagContentProviders.forEach { provider -> - with(provider) { - contentForBrief(sourceSet, tag) - } - } - } - } - } - } + contentForCustomTagsBrief(it) } } } @@ -708,6 +694,22 @@ open class DefaultPageCreator( } } + private fun DocumentableContentBuilder.contentForCustomTagsBrief(documentable: Documentable) { + val customTags = documentable.customTags + if (customTags.isEmpty()) return + + documentable.sourceSets.forEach { sourceSet -> + customTags.forEach { (tagName, sourceSetTag) -> + sourceSetTag[sourceSet]?.let { tag -> + customTagContentProviders.forEach { provider -> + with(provider) { + contentForBrief(sourceSet, tag) + } + } + } + } + } + } protected open fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last() From 958edd1bcad664115b73854fb3bbf03da29c6fa3 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Mon, 14 Feb 2022 18:34:31 +0300 Subject: [PATCH 6/8] Filter out tag content providers and make since kotlin brief a one-liner --- plugins/base/api/base.api | 2 ++ .../pages/tags/CustomTagContentProvider.kt | 8 +++++++ .../tags/SinceKotlinTagContentProvider.kt | 24 +++++++------------ .../documentables/DefaultPageCreator.kt | 4 ++-- plugins/mathjax/api/mathjax.api | 1 + .../mathjax/src/main/kotlin/MathjaxPlugin.kt | 7 +++--- 6 files changed, 26 insertions(+), 20 deletions(-) diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 121ef45f49..b17b405294 100644 --- a/plugins/base/api/base.api +++ b/plugins/base/api/base.api @@ -1272,6 +1272,7 @@ public final class org/jetbrains/dokka/base/transformers/pages/sourcelinks/Sourc public abstract interface class org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider { public abstract fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V public abstract fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public abstract fun isApplicable (Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)Z } public final class org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider$DefaultImpls { @@ -1283,6 +1284,7 @@ public final class org/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinT public static final field INSTANCE Lorg/jetbrains/dokka/base/transformers/pages/tags/SinceKotlinTagContentProvider; public fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V public fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public fun isApplicable (Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)Z } public final class org/jetbrains/dokka/base/translators/descriptors/DRIWithPlatformInfo { diff --git a/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt b/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt index b167ffa417..e818ef1ddc 100644 --- a/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt +++ b/plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt @@ -3,6 +3,7 @@ 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 @@ -20,6 +21,13 @@ import org.jetbrains.dokka.model.doc.CustomTagWrapper */ 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 diff --git a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt index 904784c08d..9b69e54151 100644 --- a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt +++ b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt @@ -8,31 +8,25 @@ import org.jetbrains.dokka.pages.TextStyle object SinceKotlinTagContentProvider : CustomTagContentProvider { - private const val TAG_NAME = "Since Kotlin" + 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 ) { - sinceKotlinBlock(sourceSet, customTag) + 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 ) { - sinceKotlinBlock(sourceSet, customTag) - } - - private fun DocumentableContentBuilder.sinceKotlinBlock( - sourceSet: DokkaConfiguration.DokkaSourceSet, - customTag: CustomTagWrapper - ) { - if (customTag.name == TAG_NAME) { - group(sourceSets = setOf(sourceSet), kind = ContentKind.Comment, styles = setOf(TextStyle.Block)) { - header(4, customTag.name) - comment(customTag.root) - } - } + text(customTag.name + " ", styles = setOf(TextStyle.Bold)) + comment(customTag.root) } } \ 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 c6dc0b8ce0..946d6416ce 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -349,7 +349,7 @@ open class DefaultPageCreator( platforms.forEach { platform -> customTags.forEach { (tagName, sourceSetTag) -> sourceSetTag[platform]?.let { tag -> - customTagContentProviders.forEach { provider -> + customTagContentProviders.filter { it.isApplicable(tag) }.forEach { provider -> with(provider) { contentForDescription(platform, tag) } @@ -701,7 +701,7 @@ open class DefaultPageCreator( documentable.sourceSets.forEach { sourceSet -> customTags.forEach { (tagName, sourceSetTag) -> sourceSetTag[sourceSet]?.let { tag -> - customTagContentProviders.forEach { provider -> + customTagContentProviders.filter { it.isApplicable(tag) }.forEach { provider -> with(provider) { contentForBrief(sourceSet, tag) } diff --git a/plugins/mathjax/api/mathjax.api b/plugins/mathjax/api/mathjax.api index a3a15839a0..da5caeb213 100644 --- a/plugins/mathjax/api/mathjax.api +++ b/plugins/mathjax/api/mathjax.api @@ -8,6 +8,7 @@ public final class org/jetbrains/dokka/mathjax/MathjaxTagContentProvider : org/j public static final field INSTANCE Lorg/jetbrains/dokka/mathjax/MathjaxTagContentProvider; public fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V public fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V + public fun isApplicable (Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)Z } public final class org/jetbrains/dokka/mathjax/MathjaxTransformer : org/jetbrains/dokka/transformers/pages/PageTransformer { diff --git a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt index dd8d15ee09..89c13202a8 100644 --- a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt +++ b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt @@ -42,12 +42,13 @@ object MathjaxTransformer : PageTransformer { } object MathjaxTagContentProvider : CustomTagContentProvider { + + override fun isApplicable(customTag: CustomTagWrapper) = customTag.name == ANNOTATION + override fun DocumentableContentBuilder.contentForDescription( sourceSet: DokkaConfiguration.DokkaSourceSet, customTag: CustomTagWrapper ) { - if (customTag.name == ANNOTATION) { - comment(customTag.root, sourceSets = setOf(sourceSet)) - } + comment(customTag.root, sourceSets = setOf(sourceSet)) } } \ No newline at end of file From 189301aca72d189a5a0f04630c35fd8c12979e32 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Wed, 16 Feb 2022 16:24:25 +0300 Subject: [PATCH 7/8] Add padding to "Since Kotlin" block in brief description --- core/api/core.api | 1 + core/src/main/kotlin/pages/ContentNodes.kt | 3 ++- .../base/src/main/kotlin/renderers/html/HtmlRenderer.kt | 1 + .../pages/tags/SinceKotlinTagContentProvider.kt | 6 ++++-- plugins/base/src/main/resources/dokka/styles/style.css | 8 +++++++- 5 files changed, 15 insertions(+), 4 deletions(-) diff --git a/core/api/core.api b/core/api/core.api index 6ce8ba8480..8b76c00efc 100644 --- a/core/api/core.api +++ b/core/api/core.api @@ -4216,6 +4216,7 @@ public final class org/jetbrains/dokka/pages/TextStyle : java/lang/Enum, org/jet public static final field BreakableAfter Lorg/jetbrains/dokka/pages/TextStyle; public static final field Cover Lorg/jetbrains/dokka/pages/TextStyle; public static final field Indented Lorg/jetbrains/dokka/pages/TextStyle; + public static final field InlineComment Lorg/jetbrains/dokka/pages/TextStyle; public static final field Italic Lorg/jetbrains/dokka/pages/TextStyle; public static final field Monospace Lorg/jetbrains/dokka/pages/TextStyle; public static final field Paragraph Lorg/jetbrains/dokka/pages/TextStyle; diff --git a/core/src/main/kotlin/pages/ContentNodes.kt b/core/src/main/kotlin/pages/ContentNodes.kt index 293fe6c464..23baa482c8 100644 --- a/core/src/main/kotlin/pages/ContentNodes.kt +++ b/core/src/main/kotlin/pages/ContentNodes.kt @@ -383,7 +383,8 @@ enum class TokenStyle : Style { } enum class TextStyle : Style { - Bold, Italic, Strong, Strikethrough, Paragraph, Block, Span, Monospace, Indented, Cover, UnderCoverText, BreakableAfter, Breakable + Bold, Italic, Strong, Strikethrough, Paragraph, + Block, Span, Monospace, Indented, Cover, UnderCoverText, BreakableAfter, Breakable, InlineComment } enum class ContentStyle : Style { diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt index 2906e8f277..2d8f88a61d 100644 --- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt +++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt @@ -113,6 +113,7 @@ open class HtmlRenderer( childrenCallback() } } + node.hasStyle(TextStyle.InlineComment) -> div("inline-comment") { childrenCallback() } node.dci.kind == ContentKind.BriefComment -> div("brief $additionalClasses") { childrenCallback() } node.dci.kind == ContentKind.Cover -> div("cover $additionalClasses") { //TODO this can be removed childrenCallback() diff --git a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt index 9b69e54151..c9010421b9 100644 --- a/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt +++ b/plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt @@ -26,7 +26,9 @@ object SinceKotlinTagContentProvider : CustomTagContentProvider { sourceSet: DokkaConfiguration.DokkaSourceSet, customTag: CustomTagWrapper ) { - text(customTag.name + " ", styles = setOf(TextStyle.Bold)) - comment(customTag.root) + 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 diff --git a/plugins/base/src/main/resources/dokka/styles/style.css b/plugins/base/src/main/resources/dokka/styles/style.css index cc8b682396..94200bd1ca 100644 --- a/plugins/base/src/main/resources/dokka/styles/style.css +++ b/plugins/base/src/main/resources/dokka/styles/style.css @@ -890,7 +890,13 @@ td.content { display: block; } -.table-row .with-platform-tabs .sourceset-depenent-content .brief { +.table-row .inline-comment { + padding-top: 8px; + padding-bottom: 8px; +} + +.table-row .with-platform-tabs .sourceset-depenent-content .brief, +.table-row .with-platform-tabs .sourceset-depenent-content .inline-comment { padding: 8px; } From 0ef0fb63531fe3f23ae29f9902242b9c97b42336 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 17 Feb 2022 13:12:14 +0300 Subject: [PATCH 8/8] Remove mathjax custom tag content provider to be contributed separately --- plugins/mathjax/api/mathjax.api | 8 -------- .../mathjax/src/main/kotlin/MathjaxPlugin.kt | 18 ------------------ 2 files changed, 26 deletions(-) diff --git a/plugins/mathjax/api/mathjax.api b/plugins/mathjax/api/mathjax.api index da5caeb213..47612ecb78 100644 --- a/plugins/mathjax/api/mathjax.api +++ b/plugins/mathjax/api/mathjax.api @@ -1,16 +1,8 @@ public final class org/jetbrains/dokka/mathjax/MathjaxPlugin : org/jetbrains/dokka/plugability/DokkaPlugin { public fun ()V - public final fun getMathjaxTagContentProvider ()Lorg/jetbrains/dokka/plugability/Extension; public final fun getTransformer ()Lorg/jetbrains/dokka/plugability/Extension; } -public final class org/jetbrains/dokka/mathjax/MathjaxTagContentProvider : org/jetbrains/dokka/base/transformers/pages/tags/CustomTagContentProvider { - public static final field INSTANCE Lorg/jetbrains/dokka/mathjax/MathjaxTagContentProvider; - public fun contentForBrief (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V - public fun contentForDescription (Lorg/jetbrains/dokka/base/translators/documentables/PageContentBuilder$DocumentableContentBuilder;Lorg/jetbrains/dokka/DokkaConfiguration$DokkaSourceSet;Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)V - public fun isApplicable (Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)Z -} - public final class org/jetbrains/dokka/mathjax/MathjaxTransformer : org/jetbrains/dokka/transformers/pages/PageTransformer { public static final field INSTANCE Lorg/jetbrains/dokka/mathjax/MathjaxTransformer; public fun invoke (Lorg/jetbrains/dokka/pages/RootPageNode;)Lorg/jetbrains/dokka/pages/RootPageNode; diff --git a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt index 89c13202a8..6a00a3daa3 100644 --- a/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt +++ b/plugins/mathjax/src/main/kotlin/MathjaxPlugin.kt @@ -16,12 +16,6 @@ class MathjaxPlugin : DokkaPlugin() { val transformer by extending { CoreExtensions.pageTransformer with MathjaxTransformer } - - val mathjaxTagContentProvider by extending { - plugin().customTagContentProvider with MathjaxTagContentProvider order { - before(plugin().sinceKotlinTagContentProvider) - } - } } private const val ANNOTATION = "usesMathJax" @@ -40,15 +34,3 @@ object MathjaxTransformer : PageTransformer { .orEmpty() .any { (it as? CustomTagWrapper)?.name == ANNOTATION } } - -object MathjaxTagContentProvider : CustomTagContentProvider { - - override fun isApplicable(customTag: CustomTagWrapper) = customTag.name == ANNOTATION - - override fun DocumentableContentBuilder.contentForDescription( - sourceSet: DokkaConfiguration.DokkaSourceSet, - customTag: CustomTagWrapper - ) { - comment(customTag.root, sourceSets = setOf(sourceSet)) - } -} \ No newline at end of file