From 12a386bb7185f862a1cbd831e6856c4235953833 Mon Sep 17 00:00:00 2001 From: Vadim Mishenev Date: Fri, 30 Jun 2023 16:44:20 +0300 Subject: Generate dedicated pages for typealiases (#3051) --- .../renderers/html/NavigationDataProvider.kt | 1 + .../main/kotlin/renderers/html/NavigationPage.kt | 1 + .../kotlin/renderers/html/htmlPreprocessors.kt | 1 + .../documentables/DefaultPageCreator.kt | 51 ++++++++++++++-------- .../dokka/images/nav-icons/typealias-kotlin.svg | 9 ++++ .../base/src/main/resources/dokka/styles/style.css | 4 ++ 6 files changed, 49 insertions(+), 18 deletions(-) create mode 100644 plugins/base/src/main/resources/dokka/images/nav-icons/typealias-kotlin.svg (limited to 'plugins/base/src/main') diff --git a/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt index 4dae21c8..be1b0fcf 100644 --- a/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt +++ b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt @@ -41,6 +41,7 @@ abstract class NavigationDataProvider { val isJava = documentable?.hasAnyJavaSources() ?: false when (documentable) { + is DTypeAlias -> NavigationNodeIcon.TYPEALIAS_KT is DClass -> when { documentable.isException -> NavigationNodeIcon.EXCEPTION documentable.isAbstract() -> { diff --git a/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt b/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt index fc17983d..9543c388 100644 --- a/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt +++ b/plugins/base/src/main/kotlin/renderers/html/NavigationPage.kt @@ -109,6 +109,7 @@ enum class NavigationNodeIcon( FUNCTION("function"), EXCEPTION("exception-class"), OBJECT("object"), + TYPEALIAS_KT("typealias-kt"), VAL("val"), VAR("var"); diff --git a/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt b/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt index 7ffcd9e3..a213bce9 100644 --- a/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt +++ b/plugins/base/src/main/kotlin/renderers/html/htmlPreprocessors.kt @@ -120,6 +120,7 @@ object AssetsInstaller : PageTransformer { "images/nav-icons/interface.svg", "images/nav-icons/interface-kotlin.svg", "images/nav-icons/object.svg", + "images/nav-icons/typealias-kotlin.svg", ) override fun invoke(input: RootPageNode) = input.modified( diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index 1abd3441..ffc7fd85 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -42,21 +42,34 @@ open class DefaultPageCreator( open fun pageForModule(m: DModule): ModulePageNode = ModulePageNode(m.name.ifEmpty { "" }, contentForModule(m), listOf(m), m.packages.map(::pageForPackage)) + /** + * We want to generate separated pages for no-actual typealias. + * Actual typealias are displayed on pages for their expect class (trough [ActualTypealias] extra). + * + * @see ActualTypealias + */ + private fun List.filterOutActualTypeAlias(): List { + fun List.hasExpectClass(dri: DRI) = find { it is DClasslike && it.dri == dri && it.expectPresentInSet != null } != null + 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) - p.classlikes.mergeClashingDocumentable().map(::pageForClasslikes) + + (p.classlikes + p.typealiases).filterOutActualTypeAlias() + .mergeClashingDocumentable().map(::pageForClasslikes) + p.functions.mergeClashingDocumentable().map(::pageForFunctions) + p.properties.mergeClashingDocumentable().map(::pageForProperties) else - p.classlikes.renameClashingDocumentable().map(::pageForClasslike) + + (p.classlikes + p.typealiases).filterOutActualTypeAlias() + .renameClashingDocumentable().map(::pageForClasslike) + p.functions.renameClashingDocumentable().map(::pageForFunction) + p.properties.mapNotNull(::pageForProperty) ) open fun pageForEnumEntry(e: DEnumEntry): ClasslikePageNode = pageForEnumEntries(listOf(e)) - open fun pageForClasslike(c: DClasslike): ClasslikePageNode = pageForClasslikes(listOf(c)) + open fun pageForClasslike(c: Documentable): ClasslikePageNode = pageForClasslikes(listOf(c)) open fun pageForEnumEntries(documentables: List): ClasslikePageNode { val dri = documentables.dri.also { @@ -83,33 +96,38 @@ open class DefaultPageCreator( ) } - open fun pageForClasslikes(documentables: List): ClasslikePageNode { + /** + * @param documentables a list of [DClasslike] and [DTypeAlias] with the same dri in different sourceSets + */ + 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!") } } + val classlikes = documentables.filterIsInstance() + val constructors = - if (documentables.shouldDocumentConstructors()) { - documentables.flatMap { (it as? WithConstructors)?.constructors ?: emptyList() } + if (classlikes.shouldDocumentConstructors()) { + classlikes.flatMap { (it as? WithConstructors)?.constructors ?: emptyList() } } else { emptyList() } - val classlikes = documentables.flatMap { it.classlikes } - val functions = documentables.flatMap { it.filteredFunctions } - val props = documentables.flatMap { it.filteredProperties } - val entries = documentables.flatMap { if (it is DEnum) it.entries else emptyList() } + val nestedClasslikes = classlikes.flatMap { it.classlikes } + val functions = classlikes.flatMap { it.filteredFunctions } + val props = classlikes.flatMap { it.filteredProperties } + val entries = classlikes.flatMap { if (it is DEnum) it.entries else emptyList() } val childrenPages = constructors.map(::pageForFunction) + if (mergeImplicitExpectActualDeclarations) - classlikes.mergeClashingDocumentable().map(::pageForClasslikes) + + nestedClasslikes.mergeClashingDocumentable().map(::pageForClasslikes) + functions.mergeClashingDocumentable().map(::pageForFunctions) + props.mergeClashingDocumentable().map(::pageForProperties) + entries.mergeClashingDocumentable().map(::pageForEnumEntries) else - classlikes.renameClashingDocumentable().map(::pageForClasslike) + + nestedClasslikes.renameClashingDocumentable().map(::pageForClasslike) + functions.renameClashingDocumentable().map(::pageForFunction) + props.renameClashingDocumentable().mapNotNull(::pageForProperty) + entries.renameClashingDocumentable().map(::pageForEnumEntry) @@ -329,7 +347,7 @@ open class DefaultPageCreator( sortedWith(compareBy({ it.name }, { it.parameters.size }, { it.dri.toString() })) /** - * @param documentables a list of [DClasslike] and [DEnumEntry] with the same dri in different sourceSets + * @param documentables a list of [DClasslike] and [DEnumEntry] and [DTypeAlias] with the same dri in different sourceSets */ protected open fun contentForClasslikesAndEntries(documentables: List): ContentGroup = contentBuilder.contentFor(documentables.dri, documentables.sourceSets) { @@ -477,8 +495,7 @@ open class DefaultPageCreator( .takeIf { documentable is DProperty } }?.let { group(sourceSets = setOf(sourceSet), kind = ContentKind.BriefComment) { - if (documentable.hasSeparatePage) createBriefComment(documentable, sourceSet, it) - else comment(it.root) + createBriefComment(documentable, sourceSet, it) } } } @@ -689,6 +706,7 @@ open class DefaultPageCreator( protected open fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last() } + internal val List.sourceSets: Set get() = flatMap { it.sourceSets }.toSet() @@ -706,9 +724,6 @@ internal val Documentable.descriptions: SourceSetDependent internal val Documentable.customTags: Map> get() = groupedTags.withTypeNamed() -private val Documentable.hasSeparatePage: Boolean - get() = this !is DTypeAlias - /** * @see DefaultPageCreator.sortDivergentElementsDeterministically for usage */ diff --git a/plugins/base/src/main/resources/dokka/images/nav-icons/typealias-kotlin.svg b/plugins/base/src/main/resources/dokka/images/nav-icons/typealias-kotlin.svg new file mode 100644 index 00000000..4795069b --- /dev/null +++ b/plugins/base/src/main/resources/dokka/images/nav-icons/typealias-kotlin.svg @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/plugins/base/src/main/resources/dokka/styles/style.css b/plugins/base/src/main/resources/dokka/styles/style.css index 30f3b176..ab48a7db 100644 --- a/plugins/base/src/main/resources/dokka/styles/style.css +++ b/plugins/base/src/main/resources/dokka/styles/style.css @@ -913,6 +913,10 @@ code:not(.block) { content: url("../images/nav-icons/object.svg"); } +.nav-icon.typealias-kt::before { + content: url("../images/nav-icons/typealias-kotlin.svg"); +} + .nav-icon.val::before { content: url("../images/nav-icons/field-value.svg"); } -- cgit