From e26161b15e53a750e795f6d0d7a74e5cc1f55557 Mon Sep 17 00:00:00 2001 From: Andrzej Ratajczak Date: Wed, 15 Apr 2020 12:44:00 +0200 Subject: Fix missing expect KDoc when all actual implementations don't override KDoc --- .../DefaultDescriptorToDocumentableTranslator.kt | 104 +++++++++++++-------- .../documentables/DefaultPageCreator.kt | 22 +++-- .../documentables/PageContentBuilder.kt | 3 +- 3 files changed, 83 insertions(+), 46 deletions(-) diff --git a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt index 678ac0ec..fd6fe6bb 100644 --- a/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt +++ b/plugins/base/src/main/kotlin/translators/descriptors/DefaultDescriptorToDocumentableTranslator.kt @@ -5,6 +5,8 @@ import org.jetbrains.dokka.links.Callable import org.jetbrains.dokka.links.DRI import org.jetbrains.dokka.links.withClass import org.jetbrains.dokka.model.* +import org.jetbrains.dokka.model.doc.Constructor +import org.jetbrains.dokka.model.doc.Description import org.jetbrains.dokka.model.doc.DocumentationNode import org.jetbrains.dokka.model.properties.PropertyContainer import org.jetbrains.dokka.pages.PlatformData @@ -77,8 +79,8 @@ private class DokkaDescriptorVisitor( descriptor: PackageFragmentDescriptor, parent: DRIWithPlatformInfo ): DPackage { - val name = descriptor.fqName.asString().takeUnless { it.isBlank() } ?: - "[" + platformData.targets.joinToString(" ") + " root]"// TODO: error-prone, find a better way to do it + val name = descriptor.fqName.asString().takeUnless { it.isBlank() } + ?: "[" + platformData.targets.joinToString(" ") + " root]"// TODO: error-prone, find a better way to do it val driWithPlatform = DRI(packageName = name).withEmptyInfo() val scope = descriptor.getMemberScope() @@ -116,10 +118,10 @@ private class DokkaDescriptorVisitor( properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = descriptor.createSources(), - 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), + 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), @@ -142,10 +144,10 @@ private class DokkaDescriptorVisitor( properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = descriptor.createSources(), - 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), + 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()) @@ -167,10 +169,10 @@ private class DokkaDescriptorVisitor( properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = descriptor.createSources(), - 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), + 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), @@ -236,14 +238,14 @@ private class DokkaDescriptorVisitor( properties = scope.properties(driWithPlatform), classlikes = scope.classlikes(driWithPlatform), sources = actual, - 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), + 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 = if(isExpect) PlatformDependent.expectFrom(descriptor.modifier()) - else PlatformDependent.from(platformData, descriptor.modifier()), + modifier = if (isExpect) PlatformDependent.expectFrom(descriptor.modifier()) + else PlatformDependent.from(platformData, descriptor.modifier()), companion = descriptor.companion(driWithPlatform), platformData = listOf(platformData), extra = PropertyContainer.withAll(descriptor.additionalExtras(), descriptor.getAnnotations()) @@ -268,10 +270,10 @@ private class DokkaDescriptorVisitor( setter = descriptor.accessors.filterIsInstance().singleOrNull()?.let { visitPropertyAccessorDescriptor(it, descriptor, dri) }, - visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) - else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + visibility = if (isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData, descriptor.visibility.toDokkaVisibility()), documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), - modifier = if(isExpect) PlatformDependent.expectFrom(descriptor.modifier()) + modifier = if (isExpect) PlatformDependent.expectFrom(descriptor.modifier()) else PlatformDependent.from(platformData, descriptor.modifier()), type = descriptor.returnType!!.toBound(), platformData = listOf(platformData), @@ -301,11 +303,11 @@ private class DokkaDescriptorVisitor( parameter(index, desc, DRIWithPlatformInfo(dri, actual)) }, sources = actual, - visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) - else 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(if (!isExpect) platformData else null), - modifier = if(isExpect) PlatformDependent.expectFrom(descriptor.modifier()) + modifier = if (isExpect) PlatformDependent.expectFrom(descriptor.modifier()) else PlatformDependent.from(platformData, descriptor.modifier()), type = descriptor.returnType!!.toBound(), platformData = listOf(platformData), @@ -332,17 +334,42 @@ private class DokkaDescriptorVisitor( parameter(index, desc, DRIWithPlatformInfo(dri, actual)) }, sources = actual, - visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) - else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), - documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null), + visibility = if (isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) + else PlatformDependent.from(platformData, descriptor.visibility.toDokkaVisibility()), + documentation = descriptor.resolveDescriptorData(if (!isExpect) platformData else null).let { + if (descriptor.isPrimary) { + it.copy( + map = PlatformDependent.from(it.map.map { + Pair( + it.key, + it.value.copy(children = it.value.children.find { it is Constructor }?.root?.let { + listOf( + Description(it) + ) + } ?: emptyList()) + ) + }), + expect = it.expect?.copy(children = it.expect?.children?.find { it is Constructor }?.root?.let { + listOf( + Description(it) + ) + } ?: emptyList()) + ) + } else { + it + } + }, type = descriptor.returnType.toBound(), - modifier = if(isExpect) PlatformDependent.expectFrom(descriptor.modifier()) + modifier = if (isExpect) PlatformDependent.expectFrom(descriptor.modifier()) else PlatformDependent.from(platformData, descriptor.modifier()), generics = descriptor.typeParameters.map { it.toTypeParameter() }, platformData = listOf(platformData), - extra = PropertyContainer.withAll(descriptor.additionalExtras(), descriptor.getAnnotations()).let { - if(descriptor.isPrimary) { it + PrimaryConstructorExtra } else it - } + extra = PropertyContainer.withAll(descriptor.additionalExtras(), descriptor.getAnnotations()) + .let { + if (descriptor.isPrimary) { + it + PrimaryConstructorExtra + } else it + } ) } @@ -394,12 +421,12 @@ private class DokkaDescriptorVisitor( name, isConstructor = false, parameters = parameters, - visibility = if(isExpect) PlatformDependent.expectFrom(descriptor.visibility.toDokkaVisibility()) - else PlatformDependent.from(platformData,descriptor.visibility.toDokkaVisibility()), + 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 = if(isExpect) PlatformDependent.expectFrom(descriptor.modifier()) + modifier = if (isExpect) PlatformDependent.expectFrom(descriptor.modifier()) else PlatformDependent.from(platformData, descriptor.modifier()), receiver = descriptor.extensionReceiverParameter?.let { visitReceiverParameterDescriptor( @@ -476,7 +503,10 @@ private class DokkaDescriptorVisitor( private fun DeclarationDescriptor.resolveDescriptorData(platformData: PlatformData?): PlatformDependent = - if(platformData != null) PlatformDependent.from(platformData, getDocumentation()) else PlatformDependent.expectFrom(getDocumentation()) + if (platformData != null) PlatformDependent.from( + platformData, + getDocumentation() + ) else PlatformDependent.expectFrom(getDocumentation()) private fun ClassDescriptor.resolveClassDescriptionData(platformData: PlatformData?): ClassInfo { return ClassInfo( diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt index a70f22d8..c3621d1b 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt @@ -221,6 +221,9 @@ open class DefaultPageCreator( ?.mapValues { (_, v) -> PlatformDependent.from(v) } .orEmpty() + private inline fun GroupedTags.isNotEmptyForTag(): Boolean = + this[T::class]?.isNotEmpty() ?: false + protected open fun contentForComments( d: Documentable ): List { @@ -244,11 +247,12 @@ open class DefaultPageCreator( } fun DocumentableContentBuilder.contentForParams() { - val receiver = tags.withTypeUnnamed() - val params = tags.withTypeNamed() - - if (params.isNotEmpty()) { - header(4, kind = ContentKind.Parameters) { text("Parameters") } + if (tags.isNotEmptyForTag()) { + val receiver = tags.withTypeUnnamed() + val params = tags.withTypeNamed() + platforms.forEach { + header(4, kind = ContentKind.Parameters, platformData = setOf(it)) { text("Parameters") } + } table(kind = ContentKind.Parameters) { platforms.flatMap { platform -> val receiverRow = receiver.getOrExpect(platform)?.let { @@ -274,9 +278,11 @@ open class DefaultPageCreator( } fun DocumentableContentBuilder.contentForSeeAlso() { - val seeAlsoTags = tags.withTypeNamed() - if (seeAlsoTags.isNotEmpty()) { - header(4, kind = ContentKind.Comment) { text("See also") } + if (tags.isNotEmptyForTag()) { + val seeAlsoTags = tags.withTypeNamed() + platforms.forEach { + header(4, kind = ContentKind.Comment, platformData = setOf(it)) { text("See also") } + } table(kind = ContentKind.Comment) { platforms.flatMap { platform -> seeAlsoTags.mapNotNull { (_, see) -> diff --git a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt index d9a78d0d..a99fc6b3 100644 --- a/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt +++ b/plugins/base/src/main/kotlin/translators/documentables/PageContentBuilder.kt @@ -74,13 +74,14 @@ open class PageContentBuilder( fun header( level: Int, kind: Kind = ContentKind.Main, + platformData: Set = mainPlatformData, styles: Set