diff options
Diffstat (limited to 'plugins/base')
8 files changed, 180 insertions, 27 deletions
diff --git a/plugins/base/api/base.api b/plugins/base/api/base.api index 488d2d8d..b17b4052 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,24 @@ 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 abstract fun isApplicable (Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)Z +} + +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 fun isApplicable (Lorg/jetbrains/dokka/model/doc/CustomTagWrapper;)Z +} + public final class org/jetbrains/dokka/base/translators/descriptors/DRIWithPlatformInfo { public fun <init> (Lorg/jetbrains/dokka/links/DRI;Ljava/util/Map;)V public final fun component1 ()Lorg/jetbrains/dokka/links/DRI; @@ -1319,7 +1339,8 @@ public final class org/jetbrains/dokka/base/translators/documentables/DefaultDoc } public class org/jetbrains/dokka/base/translators/documentables/DefaultPageCreator { - public fun <init> (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 <init> (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 <init> (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 +1353,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 a26f6dcd..0443b136 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<PreMergeDocumentableTransformer>() val pageMergerStrategy by extensionPoint<PageMergerStrategy>() val commentsToContentConverter by extensionPoint<CommentsToContentConverter>() + val customTagContentProvider by extensionPoint<CustomTagContentProvider>() val signatureProvider by extensionPoint<SignatureProvider>() val locationProviderFactory by extensionPoint<LocationProviderFactory>() val externalLocationProviderFactory by extensionPoint<ExternalLocationProviderFactory>() @@ -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/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt index 2906e8f2..2d8f88a6 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/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 diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt index 18647207..a385e0e4 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<DokkaBase, DokkaBaseConfiguration>(context) private val commentsToContentConverter = context.plugin<DokkaBase>().querySingle { commentsToContentConverter } private val signatureProvider = context.plugin<DokkaBase>().querySingle { signatureProvider } + private val customTagContentProviders = context.plugin<DokkaBase>().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 c16996a0..946d6416 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<KClass<out TagWrapper>, List<Pair<DokkaSourceSet?, TagWrapper>>> @@ -29,7 +30,8 @@ open class DefaultPageCreator( configuration: DokkaBaseConfiguration?, commentsToContentConverter: CommentsToContentConverter, signatureProvider: SignatureProvider, - val logger: DokkaLogger + val logger: DokkaLogger, + val customTagContentProviders: List<CustomTagContentProvider> = emptyList() ) { protected open val contentBuilder = PageContentBuilder(commentsToContentConverter, signatureProvider, logger) @@ -341,6 +343,23 @@ open class DefaultPageCreator( } } + val customTags = d.customTags + if (customTags.isNotEmpty()) { + group(styles = setOf(TextStyle.Block)) { + platforms.forEach { platform -> + customTags.forEach { (tagName, sourceSetTag) -> + sourceSetTag[platform]?.let { tag -> + customTagContentProviders.filter { it.isApplicable(tag) }.forEach { provider -> + with(provider) { + contentForDescription(platform, 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 +376,6 @@ open class DefaultPageCreator( } } } - - contentForSinceKotlin(d) }.children } @@ -560,21 +577,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 +683,7 @@ open class DefaultPageCreator( } after(extra = PropertyContainer.empty()) { contentForBrief(it) - contentForSinceKotlin(it) + contentForCustomTagsBrief(it) } } } @@ -692,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.filter { it.isApplicable(tag) }.forEach { provider -> + with(provider) { + contentForBrief(sourceSet, tag) + } + } + } + } + } + } protected open fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last() @@ -706,6 +724,9 @@ open class DefaultPageCreator( private val Documentable.descriptions: SourceSetDependent<Description> get() = groupedTags.withTypeUnnamed<Description>() + private val Documentable.customTags: Map<String, SourceSetDependent<CustomTagWrapper>> + get() = groupedTags.withTypeNamed() + private val Documentable.hasSeparatePage: Boolean get() = this !is DTypeAlias diff --git a/plugins/base/src/main/resources/dokka/styles/style.css b/plugins/base/src/main/resources/dokka/styles/style.css index cc8b6823..94200bd1 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; } |