[Native] Add test for -Xexport-kdoc (#4249)

(*) Fix exported kdoc indentation and extra blank lines

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

@@ -16,15 +16,20 @@ object StubRenderer {
     internal fun render(stub: Stub<*>, shouldExportKDoc: Boolean): List<String> = collect {
         stub.run {
             val kDoc = if (shouldExportKDoc) {
-                this.descriptor?.extractKDocString()
+                descriptor?.extractKDocString()?.let {
+                    if (it.isNotEmpty()) {  // sometimes `findDoc` return empty string; is it a bug?
+                        +"" // Probably makes the output more readable.
+                        it.lines().forEach { it.trim().let {
+                                if (it[0] == '*') +" $it"
+                                else +"$it"
+                            }
+                        }
+                    } else null
+                }
             } 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 ->
+            comment?.let { comment ->
-                kDoc?: let { +"" } // Probably makes the output more readable.
+                kDoc ?: let { +"" } // Probably makes the output more readable.
                 +"/**"
                 comment.contentLines.forEach {
                     +" $it"
@@ -220,4 +225,3 @@ private fun DeclarationDescriptor.extractKDocString(): String? {
     return (this as? DeclarationDescriptorWithSource)?.findKDocString()
             ?: extractSerializedKdocString()
 }
-

kotlin-native/backend.native/tests/build.gradle

@@ -4729,7 +4729,7 @@ if (isAppleTarget(project)) {
         framework(frameworkName) {
             sources = ['objcexport']
             library = libraryName
-            opts = ["-Xemit-lazy-objc-header=$lazyHeader"]
+            opts = ["-Xemit-lazy-objc-header=$lazyHeader", "-Xexport-kdoc"]
         }
         swiftSources = ['objcexport']
     }

kotlin-native/backend.native/tests/objcexport/expectedLazy.h

@@ -518,6 +518,55 @@ __attribute__((swift_name("TestGH3992.B")))
 + (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
 @end;
 
+
+/**
+ * Summary class [KDocExport].
+ *
+ * @property xyzzy Doc for property xyzzy
+ * @property zzz See below.
+ */
+__attribute__((objc_subclassing_restricted))
+__attribute__((swift_name("KDocExport")))
+@interface KtKDocExport : KtBase
+
+/** Non-primary ctor KDoc: */
+- (instancetype)initWithName:(NSString *)name __attribute__((swift_name("init(name:)"))) __attribute__((objc_designated_initializer));
+- (instancetype)init __attribute__((swift_name("init()"))) __attribute__((objc_designated_initializer));
++ (instancetype)new __attribute__((availability(swift, unavailable, message="use object initializers instead")));
+
+/**
+ * @param xyzzy is documented.
+ *
+ * This is multi-line KDoc. See a blank line above.
+ */
+@property (readonly) NSString *xyzzy __attribute__((swift_name("xyzzy")));
+
+/** @property xyzzy KDoc for foo? */
+@property (readonly) NSString *foo __attribute__((swift_name("foo")));
+
+/** @property foo KDoc for yxxyz? */
+@property int32_t yxxyz __attribute__((swift_name("yxxyz")));
+@end;
+
+__attribute__((objc_subclassing_restricted))
+__attribute__((swift_name("KdocExportKt")))
+@interface KtKdocExportKt : KtBase
+
+/**
+ * Useless function [whatever]
+ *
+ * This kdoc has some additional formatting.
+ * @param a keep intact and return
+ * @return value of [a]
+ * Check for additional comment (note) below
+ */
+/**
+ @note This method converts instances of IllegalArgumentException to errors.
+ Other uncaught Kotlin exceptions are fatal.
+*/
++ (NSString * _Nullable)whateverA:(NSString *)a error:(NSError * _Nullable * _Nullable)error __attribute__((swift_name("whatever(a:)")));
+@end;
+
 __attribute__((objc_subclassing_restricted))
 __attribute__((swift_name("Kt35940Kt")))
 @interface KtKt35940Kt : KtBase

kotlin-native/backend.native/tests/objcexport/kdocExport.kt

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2010-2021 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package kdocExport
+
+/**
+ * Summary class [KDocExport].
+ *
+ * @property xyzzy Doc for property xyzzy
+ * @property zzz See below.
+ */
+
+// Expected: this comment shall not affect KDoc (i.e. kdoc above is still OK)
+class KDocExport() {
+    /**
+     * @param xyzzy is documented.
+     *
+     * This is multi-line KDoc. See a blank line above.
+     */
+    val xyzzy: String = "String example"
+
+    /** Non-primary ctor KDoc: */
+    constructor(name: String) : this() {
+        println(name)
+    }
+
+            /** @property xyzzy KDoc for foo? */
+    val foo = "foo"
+    /** @property foo KDoc for yxxyz? */
+    var yxxyz = 0;
+}
+
+
+/**
+ * Useless function [whatever]
+ *
+ * This kdoc has some additional formatting.
+ * @param a keep intact and return
+ * @return value of [a]
+ * Check for additional comment (note) below
+ */
+@Throws(IllegalArgumentException::class)
+fun whatever(a:String) = a