Fix missing expect KDoc when all actual implementations don't override KDoc

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<PropertySetterDescriptor>().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<DFunction>(descriptor.additionalExtras(), descriptor.getAnnotations()).let {
-                if(descriptor.isPrimary) { it + PrimaryConstructorExtra } else it
-            }
+            extra = PropertyContainer.withAll<DFunction>(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<DocumentationNode> =
-        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 <reified T : TagWrapper> GroupedTags.isNotEmptyForTag(): Boolean =
+            this[T::class]?.isNotEmpty() ?: false
+
     protected open fun contentForComments(
         d: Documentable
     ): List<ContentNode> {
@@ -244,11 +247,12 @@ open class DefaultPageCreator(
         }
 
         fun DocumentableContentBuilder.contentForParams() {
-            val receiver = tags.withTypeUnnamed<Receiver>()
-            val params = tags.withTypeNamed<Param>()
-
-            if (params.isNotEmpty()) {
-                header(4, kind = ContentKind.Parameters) { text("Parameters") }
+            if (tags.isNotEmptyForTag<Param>()) {
+                val receiver = tags.withTypeUnnamed<Receiver>()
+                val params = tags.withTypeNamed<Param>()
+                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<See>()
-            if (seeAlsoTags.isNotEmpty()) {
-                header(4, kind = ContentKind.Comment) { text("See also") }
+            if (tags.isNotEmptyForTag<See>()) {
+                val seeAlsoTags = tags.withTypeNamed<See>()
+                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<PlatformData> = mainPlatformData,
             styles: Set<Style> = mainStyles,
             extra: PropertyContainer<ContentNode> = mainExtra,
             block: DocumentableContentBuilder.() -> Unit
         ) {
             contents += ContentHeader(
                 level,
-                contentFor(mainDRI, mainPlatformData, kind, styles, extra, block)
+                contentFor(mainDRI, platformData, kind, styles, extra, block)
             )
         }