From 8ef04b5d6bb46a5fbd9cea9b8d08048bc9f03879 Mon Sep 17 00:00:00 2001 From: Filip Zybała Date: Thu, 19 Mar 2020 16:04:55 +0100 Subject: Fixed expected-actual merging. Refactored contentForComments. --- core/src/main/kotlin/model/Documentable.kt | 1 + .../src/main/kotlin/renderers/html/HtmlRenderer.kt | 2 +- .../DefaultDescriptorToDocumentableTranslator.kt | 74 ++++++++++++++-------- .../documentables/DefaultPageCreator.kt | 58 ++++++++++------- 4 files changed, 85 insertions(+), 50 deletions(-) diff --git a/core/src/main/kotlin/model/Documentable.kt b/core/src/main/kotlin/model/Documentable.kt index 6b41b51e..6215be18 100644 --- a/core/src/main/kotlin/model/Documentable.kt +++ b/core/src/main/kotlin/model/Documentable.kt @@ -40,6 +40,7 @@ data class PlatformDependent( companion object { fun empty(): PlatformDependent = PlatformDependent(emptyMap()) fun from(platformData: PlatformData, element: T) = PlatformDependent(mapOf(platformData to element)) + fun expectFrom(element: T) = PlatformDependent(map = emptyMap(), expect = element) } } diff --git a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt index 7f953c57..f38d68dd 100644 --- a/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt +++ b/plugins/base/src/main/kotlin/renderers/html/HtmlRenderer.kt @@ -46,7 +46,7 @@ open class HtmlRenderer( consumer.onTagContentUnsafe { +distinct.keys.single() } else distinct.forEach { text, platforms -> - consumer.onTagContentUnsafe { +platforms.joinToString(prefix = "$text [", postfix = "]") { it.name } } + consumer.onTagContentUnsafe { +platforms.joinToString(prefix = " [", postfix = "] $text") { it.platformType.key } } } } diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index c30d99b7..ccee7269 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -96,7 +96,9 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv private fun interfaceDescriptor(descriptor: ClassDescriptor, parent: DRIWithPlatformInfo): DInterface { val driWithPlatform = parent.dri.withClass(descriptor.name.asString()).withEmptyInfo() val scope = descriptor.unsubstitutedMemberScope - val info = descriptor.resolveClassDescriptionData(platformData) + val isExpect = descriptor.isExpect + val info = descriptor.resolveClassDescriptionData(if (!isExpect) platformData else null) + return DInterface( dri = driWithPlatform.dri, @@ -105,8 +107,10 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = descriptor.createSources(), - visibility = PlatformDependent.from(platformData, descriptor.visibility.toDokkaVisibility()), - supertypes = PlatformDependent.from(platformData, info.supertypes), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + supertypes = if(isExpect) PlatformDependent.expectFrom(info.supertypes) + else PlatformDependent.from(platformData,info.supertypes), documentation = info.docs, generics = descriptor.typeConstructor.parameters.map { it.toTypeParameter() }, companion = descriptor.companion(driWithPlatform), @@ -118,7 +122,9 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv private fun objectDescriptor(descriptor: ClassDescriptor, parent: DRIWithPlatformInfo): DObject { val driWithPlatform = parent.dri.withClass(descriptor.name.asString()).withEmptyInfo() val scope = descriptor.unsubstitutedMemberScope - val info = descriptor.resolveClassDescriptionData(platformData) + val isExpect = descriptor.isExpect + val info = descriptor.resolveClassDescriptionData(if (!isExpect) platformData else null) + return DObject( dri = driWithPlatform.dri, @@ -127,8 +133,10 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = descriptor.createSources(), - visibility = PlatformDependent(mapOf(platformData to descriptor.visibility.toDokkaVisibility())), - supertypes = PlatformDependent.from(platformData, info.supertypes), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + supertypes = if(isExpect) PlatformDependent.expectFrom(info.supertypes) + else PlatformDependent.from(platformData,info.supertypes), documentation = info.docs, platformData = listOf(platformData), extra = PropertyContainer.withAll(descriptor.additionalExtras(), descriptor.getAnnotations()) @@ -138,7 +146,8 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv private fun enumDescriptor(descriptor: ClassDescriptor, parent: DRIWithPlatformInfo): DEnum { val driWithPlatform = parent.dri.withClass(descriptor.name.asString()).withEmptyInfo() val scope = descriptor.unsubstitutedMemberScope - val info = descriptor.resolveClassDescriptionData(platformData) + val isExpect = descriptor.isExpect + val info = descriptor.resolveClassDescriptionData(if (!isExpect) platformData else null) return DEnum( dri = driWithPlatform.dri, @@ -149,8 +158,10 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = descriptor.createSources(), - visibility = PlatformDependent(mapOf(platformData to descriptor.visibility.toDokkaVisibility())), - supertypes = PlatformDependent.from(platformData, info.supertypes), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + supertypes = if(isExpect) PlatformDependent.expectFrom(info.supertypes) + else PlatformDependent.from(platformData,info.supertypes), documentation = info.docs, companion = descriptor.companion(driWithPlatform), platformData = listOf(platformData), @@ -161,11 +172,12 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv private fun enumEntryDescriptor(descriptor: ClassDescriptor, parent: DRIWithPlatformInfo): DEnumEntry { val driWithPlatform = parent.dri.withClass(descriptor.name.asString()).withEmptyInfo() val scope = descriptor.unsubstitutedMemberScope + val isExpect = descriptor.isExpect return DEnumEntry( dri = driWithPlatform.dri, name = descriptor.name.asString(), - documentation = descriptor.resolveDescriptorData(platformData), + documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), classlikes = scope.classlikes(driWithPlatform), functions = scope.functions(driWithPlatform), properties = scope.properties(driWithPlatform), @@ -197,7 +209,8 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv private fun classDescriptor(descriptor: ClassDescriptor, parent: DRIWithPlatformInfo): DClass { val driWithPlatform = parent.dri.withClass(descriptor.name.asString()).withEmptyInfo() val scope = descriptor.unsubstitutedMemberScope - val info = descriptor.resolveClassDescriptionData(platformData) + val isExpect = descriptor.isExpect + val info = descriptor.resolveClassDescriptionData(if (!isExpect) platformData else null) val actual = descriptor.createSources() return DClass( @@ -214,12 +227,14 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = actual, - visibility = PlatformDependent.from(platformData, descriptor.visibility.toDokkaVisibility()), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + supertypes = if(isExpect) PlatformDependent.expectFrom(info.supertypes) + else PlatformDependent.from(platformData,info.supertypes), generics = descriptor.typeConstructor.parameters.map { it.toTypeParameter() }, documentation = info.docs, modifier = descriptor.modifier(), companion = descriptor.companion(driWithPlatform), - supertypes = PlatformDependent.from(platformData, info.supertypes), platformData = listOf(platformData), extra = PropertyContainer.withAll(descriptor.additionalExtras(), descriptor.getAnnotations()) ) @@ -227,6 +242,7 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv override fun visitPropertyDescriptor(descriptor: PropertyDescriptor, parent: DRIWithPlatformInfo): DProperty { val dri = parent.dri.copy(callable = Callable.from(descriptor)) + val isExpect = descriptor.isExpect val actual = descriptor.createSources() return DProperty( @@ -242,8 +258,9 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv setter = descriptor.accessors.filterIsInstance().singleOrNull()?.let { visitPropertyAccessorDescriptor(it, descriptor, dri) }, - visibility = PlatformDependent(mapOf(platformData to descriptor.visibility.toDokkaVisibility())), - documentation = descriptor.resolveDescriptorData(platformData), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), modifier = descriptor.modifier(), type = descriptor.returnType!!.toBound(), platformData = listOf(platformData), @@ -253,6 +270,7 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv override fun visitFunctionDescriptor(descriptor: FunctionDescriptor, parent: DRIWithPlatformInfo): DFunction { val dri = parent.dri.copy(callable = Callable.from(descriptor)) + val isExpect = descriptor.isExpect val actual = descriptor.createSources() return DFunction( @@ -266,9 +284,10 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv parameter(index, desc, DRIWithPlatformInfo(dri, actual)) }, sources = actual, - visibility = PlatformDependent.from(platformData, descriptor.visibility.toDokkaVisibility()), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), generics = descriptor.typeParameters.map { it.toTypeParameter() }, - documentation = descriptor.resolveDescriptorData(platformData), + documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), modifier = descriptor.modifier(), type = descriptor.returnType!!.toBound(), platformData = listOf(platformData), @@ -279,6 +298,8 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv override fun visitConstructorDescriptor(descriptor: ConstructorDescriptor, parent: DRIWithPlatformInfo): DFunction { val dri = parent.dri.copy(callable = Callable.from(descriptor)) val actual = descriptor.createSources() + val isExpect = descriptor.isExpect + return DFunction( dri = dri, name = "", @@ -290,8 +311,9 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv parameter(index, desc, DRIWithPlatformInfo(dri, actual)) }, sources = actual, - visibility = PlatformDependent(mapOf(platformData to descriptor.visibility.toDokkaVisibility())), - documentation = descriptor.resolveDescriptorData(platformData), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), type = descriptor.returnType.toBound(), modifier = descriptor.modifier(), generics = descriptor.typeParameters.map { it.toTypeParameter() }, @@ -320,13 +342,14 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv ): DFunction { val dri = parent.copy(callable = Callable.from(descriptor)) val isGetter = descriptor is PropertyGetterDescriptor + val isExpect = descriptor.isExpect fun PropertyDescriptor.asParameter(parent: DRI) = DParameter( parent.copy(target = 1), this.name.asString(), type = this.type.toBound(), - documentation = descriptor.resolveDescriptorData(platformData), + documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), platformData = listOf(platformData), extra = PropertyContainer.withAll(descriptor.additionalExtras(), descriptor.getAnnotations()) ) @@ -349,8 +372,9 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv name, isConstructor = false, parameters = parameters, - visibility = PlatformDependent(mapOf(platformData to descriptor.visibility.toDokkaVisibility())), - documentation = descriptor.resolveDescriptorData(platformData), + visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), type = descriptor.returnType!!.toBound(), generics = descriptor.typeParameters.map { it.toTypeParameter() }, modifier = descriptor.modifier(), @@ -409,10 +433,10 @@ private class DokkaDescriptorVisitor( // TODO: close this class and make it priv .map { enumEntryDescriptor(it, parent) } - private fun DeclarationDescriptor.resolveDescriptorData(platformData: PlatformData): PlatformDependent = - PlatformDependent.from(platformData, getDocumentation()) + private fun DeclarationDescriptor.resolveDescriptorData(platformData: PlatformData?): PlatformDependent = + if(platformData != null) PlatformDependent.from(platformData, getDocumentation()) else PlatformDependent.expectFrom(getDocumentation()) - private fun ClassDescriptor.resolveClassDescriptionData(platformData: PlatformData): ClassInfo { + private fun ClassDescriptor.resolveClassDescriptionData(platformData: PlatformData?): ClassInfo { return ClassInfo( (getSuperInterfaces() + getAllSuperclassesWithoutAny()).map { DRI.from(it) }, resolveDescriptorData(platformData) diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index 02b9ea2a..3f3ebe3a 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -11,6 +11,7 @@ import org.jetbrains.dokka.model.doc.TagWrapper import org.jetbrains.dokka.model.properties.WithExtraProperties import org.jetbrains.dokka.pages.* import org.jetbrains.dokka.utilities.DokkaLogger +import org.jetbrains.kotlin.backend.common.phaser.defaultDumper open class DefaultPageCreator( commentsToContentConverter: CommentsToContentConverter, @@ -53,8 +54,8 @@ open class DefaultPageCreator( } protected open fun contentForPackage(p: DPackage) = contentBuilder.contentFor(p) { + header(1) { text("Package ${p.name}") } platformDependentHint(p.dri, p.platformData.toSet()){ - header(1) { text("Package ${p.name}") } +contentForScope(p, p.dri, p.platformData) } } @@ -65,8 +66,8 @@ open class DefaultPageCreator( platformData: List ) = contentBuilder.contentFor(s as Documentable) { block("Types", 2, ContentKind.Classlikes, s.classlikes, platformData.toSet()) { + link(it.name.orEmpty(), it.dri) platformDependentHint(it.dri, it.platformData.toSet()){ - link(it.name.orEmpty(), it.dri) group { +buildSignature(it) group(kind = ContentKind.BriefComment) { @@ -76,8 +77,8 @@ open class DefaultPageCreator( } } block("Functions", 2, ContentKind.Functions, s.functions, platformData.toSet()) { + link(it.name, it.dri) platformDependentHint(it.dri, it.platformData.toSet()){ - link(it.name, it.dri) group { +buildSignature(it) group(kind = ContentKind.BriefComment) { @@ -87,10 +88,9 @@ open class DefaultPageCreator( } } block("Properties", 2, ContentKind.Properties, s.properties, platformData.toSet()) { + link(it.name, it.dri) platformDependentHint(it.dri, it.platformData.toSet()){ - link(it.name, it.dri) +buildSignature(it) - breakLine() group(kind = ContentKind.BriefComment) { text(it.briefDocumentation()) } @@ -110,7 +110,7 @@ open class DefaultPageCreator( protected open fun contentForClasslike(c: DClasslike) = contentBuilder.contentFor(c) { header(1) { text(c.name.orEmpty()) } +buildSignature(c) - + breakLine() +contentForComments(c) { it !is Property } if (c is WithConstructors) { @@ -139,24 +139,33 @@ open class DefaultPageCreator( d: Documentable, filtering: (TagWrapper) -> Boolean = { true } ) = contentBuilder.contentFor(d) { - // TODO: this probably needs fixing - d.documentation.forEach { _, documentationNode -> - documentationNode.children.filter(filtering).forEach { - platformDependentHint(d.dri, d.platformData.toSet()){ - header(3) { - text(it.toHeaderString()) - d.documentation.keys.joinToString(prefix = "[", postfix = "]", separator = ", ") + d.documentation.map{(k,v) -> (k to v.children.filter(filtering).map{p -> (k to p)})}.flatMap { it.second } + .groupBy { it.second.toHeaderString() }.mapValues {(k,v) -> v.groupBy { it.first }} + .forEach{ groupedByHeader -> + header(3) { text(groupedByHeader.key) } + d.documentation.expect?.also{ + it.children.filter(filtering).filter{it.toHeaderString() == groupedByHeader.key} + .forEach { + comment(it.root) + breakLine() + } + } + platformDependentHint(d.dri,groupedByHeader.value.keys){ + groupedByHeader.value.forEach{ + group(d.dri, setOf(it.key)){ + it.value.forEach { + comment(it.second.root) + } + breakLine() + } } - comment(it.root) - text("\n") } } - } }.children protected open fun contentForFunction(f: DFunction) = contentBuilder.contentFor(f) { + header(1) { text(f.name) } platformDependentHint(f.dri, f.platformData.toSet()){ - header(1) { text(f.name) } +buildSignature(f) +contentForComments(f) } @@ -164,11 +173,12 @@ open class DefaultPageCreator( protected open fun TagWrapper.toHeaderString() = this.javaClass.toGenericString().split('.').last() - protected open fun Documentable.briefDocumentation() = - documentation.values - .firstOrNull() - ?.children - ?.firstOrNull() - ?.root - ?.docTagSummary() ?: "" + //TODO: It isn't platform-aware and produces wrong docs Probably should use platformDependentHint + protected open fun Documentable.briefDocumentation() = " " +// documentation.values +// .firstOrNull() +// ?.children +// ?.firstOrNull() +// ?.root +// ?.docTagSummary() ?: "" } \ No newline at end of file -- cgit