[Native] Export KDoc into generated native header

kotlin-native/backend.native/cli.bc/src/org/jetbrains/kotlin/cli/bc/K2Native.kt

@@ -173,6 +173,8 @@ class K2Native : CLICompiler<K2NativeCompilerArguments>() {
                 put(OVERRIDE_CLANG_OPTIONS, arguments.clangOptions.toNonNullList())
                 put(ALLOCATION_MODE, arguments.allocator)
 
+                put(EXPORT_KDOC, arguments.exportKDoc)
+
                 put(PRINT_IR, arguments.printIr)
                 put(PRINT_IR_WITH_DESCRIPTORS, arguments.printIrWithDescriptors)
                 put(PRINT_DESCRIPTORS, arguments.printDescriptors)

kotlin-native/backend.native/cli.bc/src/org/jetbrains/kotlin/cli/bc/K2NativeCompilerArguments.kt

@@ -181,6 +181,9 @@ class K2NativeCompilerArguments : CommonCompilerArguments() {
     )
     var libraryToAddToCache: String? = null
 
+    @Argument(value = "-Xexport-kdoc", description = "Export KDoc in framework header")
+    var exportKDoc: Boolean = false
+
     @Argument(value = "-Xprint-bitcode", deprecatedName = "--print_bitcode", description = "Print llvm bitcode")
     var printBitCode: Boolean = false
 

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/Context.kt

@@ -399,6 +399,9 @@ internal class Context(config: KonanConfig) : KonanBackendContext(config) {
         printIr()
         printBitCode()
     }
+
+    fun shouldExportKDoc() = config.configuration.getBoolean(KonanConfigKeys.EXPORT_KDOC)
+
     fun shouldVerifyBitCode() = config.configuration.getBoolean(KonanConfigKeys.VERIFY_BITCODE)
 
     fun shouldPrintBitCode() = config.configuration.getBoolean(KonanConfigKeys.PRINT_BITCODE)

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/KonanCompilerFrontendServices.kt

@@ -46,7 +46,7 @@ internal fun ComponentProvider.postprocessComponents(context: Context, files: Co
     context.frontendServices = this.get<FrontendServices>()
 
     context.config.configuration.get(KonanConfigKeys.EMIT_LAZY_OBJC_HEADER_FILE)?.let {
-        this.get<ObjCExportLazy>().dumpObjCHeader(files, it)
+        this.get<ObjCExportLazy>().dumpObjCHeader(files, it, context.shouldExportKDoc())
     }
 }
 

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/KonanConfigurationKeys.kt

@@ -94,7 +94,9 @@ class KonanConfigKeys {
                 = CompilerConfigurationKey.create("arguments for clang")
         val ALLOCATION_MODE: CompilerConfigurationKey<String>
                 = CompilerConfigurationKey.create("allocation mode")
-        val PRINT_BITCODE: CompilerConfigurationKey<Boolean> 
+        val EXPORT_KDOC: CompilerConfigurationKey<Boolean>
+                = CompilerConfigurationKey.create("export KDoc into klib and framework")
+        val PRINT_BITCODE: CompilerConfigurationKey<Boolean>
                 = CompilerConfigurationKey.create("print bitcode")
         val PRINT_DESCRIPTORS: CompilerConfigurationKey<Boolean>
                 = CompilerConfigurationKey.create("print descriptors")

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/ToplevelPhases.kt

@@ -181,6 +181,7 @@ internal val serializerPhase = konanUnitPhase(
                 this.config.configuration.languageVersionSettings,
                 config.configuration.get(CommonConfigurationKeys.METADATA_VERSION)!!,
                 config.project,
+                exportKDoc = this.shouldExportKDoc(),
                 !expectActualLinker, includeOnlyModuleContent = true)
             serializedMetadata = serializer.serializeModule(moduleDescriptor)
         },

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/objcexport/ObjCExportHeaderGenerator.kt

@@ -981,6 +981,8 @@ abstract class ObjCExportHeaderGenerator internal constructor(
     private val extensions = mutableMapOf<ClassDescriptor, MutableList<CallableMemberDescriptor>>()
     private val topLevel = mutableMapOf<SourceFile, MutableList<CallableMemberDescriptor>>()
 
+    open val shouldExportKDoc = false
+
     fun build(): List<String> = mutableListOf<String>().apply {
         addImports(foundationImports)
         addImports(getAdditionalImports())
@@ -1013,7 +1015,7 @@ abstract class ObjCExportHeaderGenerator internal constructor(
         add("")
 
         stubs.forEach {
-            addAll(StubRenderer.render(it))
+            addAll(StubRenderer.render(it, shouldExportKDoc))
             add("")
         }
 

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/objcexport/ObjCExportHeaderGeneratorImpl.kt

@@ -23,6 +23,9 @@ internal class ObjCExportHeaderGeneratorImpl(
         namer: ObjCExportNamer,
         objcGenerics: Boolean
 ) : ObjCExportHeaderGenerator(moduleDescriptors, mapper, namer, objcGenerics, ProblemCollector(context)) {
+
+    override val shouldExportKDoc = context.shouldExportKDoc()
+
     private class ProblemCollector(val context: Context) : ObjCExportProblemCollector {
         override fun reportWarning(text: String) {
             context.reportCompilationWarning(text)

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/objcexport/ObjCExportLazyUtils.kt

@@ -8,9 +8,9 @@ package org.jetbrains.kotlin.backend.konan.objcexport
 import org.jetbrains.kotlin.konan.file.File
 import org.jetbrains.kotlin.psi.KtFile
 
-internal fun ObjCExportLazy.dumpObjCHeader(files: Collection<KtFile>, outputFile: String) {
+internal fun ObjCExportLazy.dumpObjCHeader(files: Collection<KtFile>, outputFile: String, shouldExportKDoc: Boolean) {
     val lines = (this.generateBase() + files.flatMap { this.translate(it) })
-            .flatMap { StubRenderer.render(it) + listOf("") }
+            .flatMap { StubRenderer.render(it, shouldExportKDoc) + listOf("") }
 
     File(outputFile).writeLines(lines)
 }

kotlin-native/backend.native/compiler/ir/backend.native/src/org/jetbrains/kotlin/backend/konan/objcexport/StubRenderer.kt

@@ -6,18 +6,32 @@
 package org.jetbrains.kotlin.backend.konan.objcexport
 
 import org.jetbrains.kotlin.descriptors.ClassDescriptor
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptor
+import org.jetbrains.kotlin.descriptors.DeclarationDescriptorWithSource
+import org.jetbrains.kotlin.backend.common.serialization.extractSerializedKdocString
+import org.jetbrains.kotlin.backend.common.serialization.metadata.findKDocString
 
 object StubRenderer {
-    fun render(stub: Stub<*>): List<String> = collect {
+    fun render(stub: Stub<*>): List<String> = render(stub, false)
+    internal fun render(stub: Stub<*>, shouldExportKDoc: Boolean): List<String> = collect {
         stub.run {
-            this.comment?.let { comment ->
+            val kDoc = if (shouldExportKDoc) {
+                this.descriptor?.extractKDocString()
+            } else null
+            kDoc?.let {
                 +"" // Probably makes the output more readable.
+                +it // Let's try to keep non-trivial kdoc formatting intact
+            }
+
+            this.comment?.let { comment ->
+                kDoc?: let { +"" } // Probably makes the output more readable.
                 +"/**"
                 comment.contentLines.forEach {
                     +" $it"
                 }
                 +"*/"
             }
+
             when (this) {
                 is ObjCProtocol -> {
                     attributes.forEach {
@@ -25,7 +39,7 @@ object StubRenderer {
                     }
                     +renderProtocolHeader()
                     +"@required"
-                    renderMembers(this)
+                    renderMembers(this, shouldExportKDoc)
                     +"@end;"
                 }
                 is ObjCInterface -> {
@@ -33,7 +47,7 @@ object StubRenderer {
                         +renderAttribute(it)
                     }
                     +renderInterfaceHeader()
-                    renderMembers(this)
+                    renderMembers(this, shouldExportKDoc)
                     +"@end;"
                 }
                 is ObjCMethod -> {
@@ -168,9 +182,9 @@ object StubRenderer {
         appendSuperProtocols(this@renderInterfaceHeader)
     }
 
-    private fun Collector.renderMembers(clazz: ObjCClass<*>) {
+    private fun Collector.renderMembers(clazz: ObjCClass<*>, shouldExportKDoc: Boolean) {
         clazz.members.forEach {
-            +render(it)
+            +render(it, shouldExportKDoc)
         }
     }
 
@@ -202,3 +216,8 @@ internal fun formatGenerics(buffer: Appendable, generics:List<String>) {
     }
 }
 
+private fun DeclarationDescriptor.extractKDocString(): String? {
+    return (this as? DeclarationDescriptorWithSource)?.findKDocString()
+            ?: extractSerializedKdocString()
+}
+