From 02f30b142aa467d3a24cc52a1fe3f2fed7ea1e33 Mon Sep 17 00:00:00 2001 From: Ignat Beresnev Date: Thu, 31 Aug 2023 20:16:01 +0200 Subject: Enable explicit API mode (#3139) --- .../DefaultDocumentableToPageTranslator.kt | 2 +- .../documentables/DefaultPageCreator.kt | 253 ++++++++++---------- .../translators/documentables/DriClashAwareName.kt | 4 +- .../documentables/PageContentBuilder.kt | 261 ++++++++++++--------- .../documentables/briefFromContentNodes.kt | 4 +- 5 files changed, 285 insertions(+), 239 deletions(-) (limited to 'plugins/base/src/main/kotlin/translators/documentables') diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt index 57cd9522..0b2597d5 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultDocumentableToPageTranslator.kt @@ -12,7 +12,7 @@ import org.jetbrains.dokka.plugability.* import org.jetbrains.dokka.transformers.documentation.DocumentableToPageTranslator import org.jetbrains.dokka.analysis.kotlin.internal.InternalKotlinAnalysisPlugin -class DefaultDocumentableToPageTranslator( +public class DefaultDocumentableToPageTranslator( context: DokkaContext ) : DocumentableToPageTranslator { private val configuration = configuration(context) diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index ec5fd193..58abee56 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -28,24 +28,26 @@ import kotlin.reflect.KClass internal typealias GroupedTags = Map, List>> -open class DefaultPageCreator( +public open class DefaultPageCreator( configuration: DokkaBaseConfiguration?, commentsToContentConverter: CommentsToContentConverter, signatureProvider: SignatureProvider, - val logger: DokkaLogger, - val customTagContentProviders: List = emptyList(), - val documentableAnalyzer: DocumentableSourceLanguageParser + public val logger: DokkaLogger, + public val customTagContentProviders: List = emptyList(), + public val documentableAnalyzer: DocumentableSourceLanguageParser ) { - protected open val contentBuilder = PageContentBuilder(commentsToContentConverter, signatureProvider, logger) + protected open val contentBuilder: PageContentBuilder = PageContentBuilder( + commentsToContentConverter, signatureProvider, logger + ) - protected val mergeImplicitExpectActualDeclarations = + protected val mergeImplicitExpectActualDeclarations: Boolean = configuration?.mergeImplicitExpectActualDeclarations ?: DokkaBaseConfiguration.mergeImplicitExpectActualDeclarationsDefault - protected val separateInheritedMembers = + protected val separateInheritedMembers: Boolean = configuration?.separateInheritedMembers ?: DokkaBaseConfiguration.separateInheritedMembersDefault - open fun pageForModule(m: DModule): ModulePageNode = + public open fun pageForModule(m: DModule): ModulePageNode = ModulePageNode(m.name.ifEmpty { "" }, contentForModule(m), listOf(m), m.packages.map(::pageForPackage)) /** @@ -59,25 +61,32 @@ open class DefaultPageCreator( return this.filterNot { it is DTypeAlias && this.hasExpectClass(it.dri) } } - open fun pageForPackage(p: DPackage): PackagePageNode = PackagePageNode( - p.name, contentForPackage(p), setOf(p.dri), listOf(p), - if (mergeImplicitExpectActualDeclarations) + public open fun pageForPackage(p: DPackage): PackagePageNode { + val children = if (mergeImplicitExpectActualDeclarations) { (p.classlikes + p.typealiases).filterOutActualTypeAlias() .mergeClashingDocumentable().map(::pageForClasslikes) + p.functions.mergeClashingDocumentable().map(::pageForFunctions) + p.properties.mergeClashingDocumentable().map(::pageForProperties) - else + } else { (p.classlikes + p.typealiases).filterOutActualTypeAlias() .renameClashingDocumentable().map(::pageForClasslike) + p.functions.renameClashingDocumentable().map(::pageForFunction) + p.properties.mapNotNull(::pageForProperty) - ) + } + return PackagePageNode( + name = p.name, + content = contentForPackage(p), + dri = setOf(p.dri), + documentables = listOf(p), + children = children + ) + } - open fun pageForEnumEntry(e: DEnumEntry): ClasslikePageNode = pageForEnumEntries(listOf(e)) + public open fun pageForEnumEntry(e: DEnumEntry): ClasslikePageNode = pageForEnumEntries(listOf(e)) - open fun pageForClasslike(c: Documentable): ClasslikePageNode = pageForClasslikes(listOf(c)) + public open fun pageForClasslike(c: Documentable): ClasslikePageNode = pageForClasslikes(listOf(c)) - open fun pageForEnumEntries(documentables: List): ClasslikePageNode { + public open fun pageForEnumEntries(documentables: List): ClasslikePageNode { val dri = documentables.dri.also { if (it.size != 1) { logger.error("Documentable dri should have the same one ${it.first()} inside the one page!") @@ -105,7 +114,7 @@ open class DefaultPageCreator( /** * @param documentables a list of [DClasslike] and [DTypeAlias] with the same dri in different sourceSets */ - open fun pageForClasslikes(documentables: List): ClasslikePageNode { + public open fun pageForClasslikes(documentables: List): ClasslikePageNode { val dri = documentables.dri.also { if (it.size != 1) { logger.error("Documentable dri should have the same one ${it.first()} inside the one page!") @@ -171,10 +180,10 @@ open class DefaultPageCreator( private fun List.mergeClashingDocumentable(): List> = groupBy { it.dri }.values.toList() - open fun pageForFunction(f: DFunction) = + public open fun pageForFunction(f: DFunction): MemberPageNode = MemberPageNode(f.nameAfterClash(), contentForFunction(f), setOf(f.dri), listOf(f)) - open fun pageForFunctions(fs: List): MemberPageNode { + public open fun pageForFunctions(fs: List): MemberPageNode { val dri = fs.dri.also { if (it.size != 1) { logger.error("Function dri should have the same one ${it.first()} inside the one page!") @@ -183,10 +192,10 @@ open class DefaultPageCreator( return MemberPageNode(fs.first().nameAfterClash(), contentForMembers(fs), dri, fs) } - open fun pageForProperty(p: DProperty): MemberPageNode? = + public open fun pageForProperty(p: DProperty): MemberPageNode? = MemberPageNode(p.nameAfterClash(), contentForProperty(p), setOf(p.dri), listOf(p)) - open fun pageForProperties(ps: List): MemberPageNode { + public open fun pageForProperties(ps: List): MemberPageNode { val dri = ps.dri.also { if (it.size != 1) { logger.error("Property dri should have the same one ${it.first()} inside the one page!") @@ -223,61 +232,65 @@ open class DefaultPageCreator( private fun Collection.splitInherited(): Pair, List> where T : Documentable, T : WithExtraProperties = partition { it.isInherited() } - protected open fun contentForModule(m: DModule) = contentBuilder.contentFor(m) { - group(kind = ContentKind.Cover) { - cover(m.name) - if (contentForDescription(m).isNotEmpty()) { - sourceSetDependentHint( - m.dri, - m.sourceSets.toSet(), - kind = ContentKind.SourceSetDependentHint, - styles = setOf(TextStyle.UnderCoverText) - ) { - +contentForDescription(m) + protected open fun contentForModule(m: DModule): ContentGroup { + return contentBuilder.contentFor(m) { + group(kind = ContentKind.Cover) { + cover(m.name) + if (contentForDescription(m).isNotEmpty()) { + sourceSetDependentHint( + m.dri, + m.sourceSets.toSet(), + kind = ContentKind.SourceSetDependentHint, + styles = setOf(TextStyle.UnderCoverText) + ) { + +contentForDescription(m) + } } } - } - block( - "Packages", - 2, - ContentKind.Packages, - m.packages, - m.sourceSets.toSet(), - needsAnchors = true, - headers = listOf( - headers("Name") - ) - ) { - val documentations = it.sourceSets.map { platform -> - it.descriptions[platform]?.also { it.root } - } - val haveSameContent = - documentations.all { it?.root == documentations.firstOrNull()?.root && it?.root != null } + block( + name = "Packages", + level = 2, + kind = ContentKind.Packages, + elements = m.packages, + sourceSets = m.sourceSets.toSet(), + needsAnchors = true, + headers = listOf( + headers("Name") + ) + ) { + val documentations = it.sourceSets.map { platform -> + it.descriptions[platform]?.also { it.root } + } + val haveSameContent = + documentations.all { it?.root == documentations.firstOrNull()?.root && it?.root != null } - link(it.name, it.dri) - if (it.sourceSets.size == 1 || (documentations.isNotEmpty() && haveSameContent)) { - documentations.first()?.let { firstParagraphComment(kind = ContentKind.Comment, content = it.root) } + link(it.name, it.dri) + if (it.sourceSets.size == 1 || (documentations.isNotEmpty() && haveSameContent)) { + documentations.first()?.let { firstParagraphComment(kind = ContentKind.Comment, content = it.root) } + } } } } - protected open fun contentForPackage(p: DPackage) = contentBuilder.contentFor(p) { - group(kind = ContentKind.Cover) { - cover("Package-level declarations") - if (contentForDescription(p).isNotEmpty()) { - sourceSetDependentHint( - p.dri, - p.sourceSets.toSet(), - kind = ContentKind.SourceSetDependentHint, - styles = setOf(TextStyle.UnderCoverText) - ) { - +contentForDescription(p) + protected open fun contentForPackage(p: DPackage): ContentGroup { + return contentBuilder.contentFor(p) { + group(kind = ContentKind.Cover) { + cover("Package-level declarations") + if (contentForDescription(p).isNotEmpty()) { + sourceSetDependentHint( + dri = p.dri, + sourcesetData = p.sourceSets.toSet(), + kind = ContentKind.SourceSetDependentHint, + styles = setOf(TextStyle.UnderCoverText) + ) { + +contentForDescription(p) + } } } - } - group(styles = setOf(ContentStyle.TabbedContent), extra = mainExtra) { - +contentForScope(p, p.dri, p.sourceSets) + group(styles = setOf(ContentStyle.TabbedContent), extra = mainExtra) { + +contentForScope(p, p.dri, p.sourceSets) + } } } @@ -400,31 +413,32 @@ open class DefaultPageCreator( constructorsToDocumented: List, dri: Set, sourceSets: Set - ) = contentBuilder.contentFor(dri, sourceSets) { - multiBlock( - "Constructors", - 2, - ContentKind.Constructors, - constructorsToDocumented.groupBy { it.name } - .map { (_, v) -> v.first().name to v }, - @Suppress("UNCHECKED_CAST") - (constructorsToDocumented as List).sourceSets, - needsAnchors = true, - extra = PropertyContainer.empty() + TabbedContentTypeExtra( - BasicTabbedContentType.CONSTRUCTOR - ), - ) { key, ds -> - link(key, ds.first().dri, kind = ContentKind.Main, styles = setOf(ContentStyle.RowTitle)) - sourceSetDependentHint( - ds.dri, - ds.sourceSets, - kind = ContentKind.SourceSetDependentHint, - styles = emptySet(), - extra = PropertyContainer.empty() - ) { - ds.forEach { - +buildSignature(it) - contentForBrief(it) + ): ContentGroup { + return contentBuilder.contentFor(dri, sourceSets) { + multiBlock( + name = "Constructors", + level = 2, + kind = ContentKind.Constructors, + groupedElements = constructorsToDocumented.groupBy { it.name } + .map { (_, v) -> v.first().name to v }, + sourceSets = (constructorsToDocumented as List).sourceSets, + needsAnchors = true, + extra = PropertyContainer.empty() + TabbedContentTypeExtra( + BasicTabbedContentType.CONSTRUCTOR + ), + ) { key, ds -> + link(key, ds.first().dri, kind = ContentKind.Main, styles = setOf(ContentStyle.RowTitle)) + sourceSetDependentHint( + dri = ds.dri, + sourceSets = ds.sourceSets, + kind = ContentKind.SourceSetDependentHint, + styles = emptySet(), + extra = PropertyContainer.empty() + ) { + ds.forEach { + +buildSignature(it) + contentForBrief(it) + } } } } @@ -434,28 +448,30 @@ open class DefaultPageCreator( entries: List, dri: Set, sourceSets: Set - ) = contentBuilder.contentFor(dri, sourceSets) { - multiBlock( - "Entries", - 2, - ContentKind.Classlikes, - entries.groupBy { it.name }.toList(), - entries.sourceSets, - needsSorting = false, - needsAnchors = true, - extra = mainExtra + TabbedContentTypeExtra(BasicTabbedContentType.ENTRY), - styles = emptySet() - ) { key, ds -> - link(key, ds.first().dri) - sourceSetDependentHint( - ds.dri, - ds.sourceSets, - kind = ContentKind.SourceSetDependentHint, - extra = PropertyContainer.empty() - ) { - ds.forEach { - +buildSignature(it) - contentForBrief(it) + ): ContentGroup { + return contentBuilder.contentFor(dri, sourceSets) { + multiBlock( + name = "Entries", + level = 2, + kind = ContentKind.Classlikes, + groupedElements = entries.groupBy { it.name }.toList(), + sourceSets = entries.sourceSets, + needsSorting = false, + needsAnchors = true, + extra = mainExtra + TabbedContentTypeExtra(BasicTabbedContentType.ENTRY), + styles = emptySet() + ) { key, ds -> + link(key, ds.first().dri) + sourceSetDependentHint( + dri = ds.dri, + sourceSets = ds.sourceSets, + kind = ContentKind.SourceSetDependentHint, + extra = PropertyContainer.empty() + ) { + ds.forEach { + +buildSignature(it) + contentForBrief(it) + } } } } @@ -520,13 +536,13 @@ open class DefaultPageCreator( } } - protected open fun contentForFunction(f: DFunction) = contentForMember(f) + protected open fun contentForFunction(f: DFunction): ContentGroup = contentForMember(f) - protected open fun contentForProperty(p: DProperty) = contentForMember(p) + protected open fun contentForProperty(p: DProperty): ContentGroup = contentForMember(p) - protected open fun contentForMember(d: Documentable) = contentForMembers(listOf(d)) + protected open fun contentForMember(d: Documentable): ContentGroup = contentForMembers(listOf(d)) - protected open fun contentForMembers(doumentables: List) = + protected open fun contentForMembers(doumentables: List): ContentGroup = contentBuilder.contentFor(doumentables.dri, doumentables.sourceSets) { group(kind = ContentKind.Cover) { cover(doumentables.first().name.orEmpty()) @@ -709,10 +725,9 @@ open class DefaultPageCreator( } } - protected open fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last() + protected open fun TagWrapper.toHeaderString(): String = this.javaClass.toGenericString().split('.').last() } - internal val List.sourceSets: Set get() = flatMap { it.sourceSets }.toSet() diff --git a/plugins/base/src/main/kotlin/translators/documentables/DriClashAwareName.kt b/plugins/base/src/main/kotlin/translators/documentables/DriClashAwareName.kt index 99c47342..362bb9b9 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DriClashAwareName.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DriClashAwareName.kt @@ -7,7 +7,7 @@ package org.jetbrains.dokka.base.translators.documentables import org.jetbrains.dokka.model.Documentable import org.jetbrains.dokka.model.properties.ExtraProperty -data class DriClashAwareName(val value: String?): ExtraProperty { - companion object : ExtraProperty.Key +public data class DriClashAwareName(val value: String?): ExtraProperty { + public companion object : ExtraProperty.Key override val key: ExtraProperty.Key = Companion } diff --git a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt index 1887e5ce..4ddda674 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt @@ -19,14 +19,14 @@ import org.jetbrains.dokka.pages.* import org.jetbrains.dokka.utilities.DokkaLogger @DslMarker -annotation class ContentBuilderMarker +public annotation class ContentBuilderMarker -open class PageContentBuilder( - val commentsConverter: CommentsToContentConverter, - val signatureProvider: SignatureProvider, - val logger: DokkaLogger +public open class PageContentBuilder( + public val commentsConverter: CommentsToContentConverter, + public val signatureProvider: SignatureProvider, + public val logger: DokkaLogger ) { - fun contentFor( + public fun contentFor( dri: DRI, sourceSets: Set, kind: Kind = ContentKind.Main, @@ -38,7 +38,7 @@ open class PageContentBuilder( .apply(block) .build(sourceSets, kind, styles, extra) - fun contentFor( + public fun contentFor( dri: Set, sourceSets: Set, kind: Kind = ContentKind.Main, @@ -50,7 +50,7 @@ open class PageContentBuilder( .apply(block) .build(sourceSets, kind, styles, extra) - fun contentFor( + public fun contentFor( d: Documentable, kind: Kind = ContentKind.Main, styles: Set