update: forward declarations in c and objc

docs/topics/multiplatform/multiplatform-compatibility-guide.md

@@ -914,7 +914,7 @@ Here's the planned deprecation cycle:
 **What's changed?**
 
 The JetBrains team has revamped the approach to forward declarations in Kotlin to make their behavior more predictable
-and prepare this functionality for the upcoming Kotlin 2.0 release. From now on:
+and prepare this functionality for the Kotlin 2.0.0 release. From now on:
 
 * You can only import forward declarations using the `cnames` or ` objcnames` packages.
 * You need to explicitly make a cast to and from the corresponding C and Objective-C forward declaration.
@@ -926,48 +926,49 @@ and prepare this functionality for the upcoming Kotlin 2.0 release. From now on:
   Now, you can only use a special forward declaration package for that: `import cnames.structs.cstructName`.
   The same is true for `objcnames`.
 
-*  Consider two objcinterop libraries, one that uses `objcnames.protocols.ForwardDeclaredProtocolProtocol` and the other that has an actual definition:
-
-    ```ObjC
-    // First objcinterop library
-    #import <Foundation/Foundation.h>
-
-    @protocol ForwardDeclaredProtocol;
-
-    NSString* consumeProtocol(id<ForwardDeclaredProtocol> s) {
-        return [NSString stringWithUTF8String:"Protocol"];
-    }
-    ```
-
-    ```ObjC
-    // Second objcinterop library
-    // Header:
-    #import <Foundation/Foundation.h>
-    @protocol ForwardDeclaredProtocol
-    @end
-    // Implementation:
-    @implementation ForwardDeclaredProtocolImpl : NSObject
-    @end;
-
-    id<ForwardDeclaredProtocol> produceProtocol() {
-        return [ForwardDeclaredProtocolImpl new];
-    }
-    ```
-
-    Previously, it was possible to transfer objects between them seamlessly. Now, an explicit `as`  cast is required
-    for the forward declaration:
-
-    ```kotlin
-    // Kotlin code:
-    fun test() {
-        consumeProtocol(produceProtocol() as objcnames.protocols.ForwardDeclaredProtocolProtocol)
-    }
-    ```
-
-    > The casting to `objcnames.protocols.ForwardDeclaredProtocolProtocol` is only allowed from the corresponding real class.
-    > Otherwise, you'll get an error.
-    >
-    {style="note"}
+* Consider two objcinterop libraries, one that uses `objcnames.protocols.ForwardDeclaredProtocolProtocol` and the other
+  that has an actual definition:
+
+  ```ObjC
+  // First objcinterop library
+  #import <Foundation/Foundation.h>
+
+  @protocol ForwardDeclaredProtocol;
+
+  NSString* consumeProtocol(id<ForwardDeclaredProtocol> s) {
+      return [NSString stringWithUTF8String:"Protocol"];
+  }
+  ```
+
+  ```ObjC
+  // Second objcinterop library
+  // Header:
+  #import <Foundation/Foundation.h>
+  @protocol ForwardDeclaredProtocol
+  @end
+  // Implementation:
+  @implementation ForwardDeclaredProtocolImpl : NSObject
+  @end;
+
+  id<ForwardDeclaredProtocol> produceProtocol() {
+      return [ForwardDeclaredProtocolImpl new];
+  }
+  ```
+
+  Previously, it was possible to transfer objects between them seamlessly. Now, an explicit `as` cast is required
+  for the forward declaration:
+
+  ```kotlin
+  // Kotlin code:
+  fun test() {
+      consumeProtocol(produceProtocol() as objcnames.protocols.ForwardDeclaredProtocolProtocol)
+  }
+  ```
+
+  > The casting to `objcnames.protocols.ForwardDeclaredProtocolProtocol` is only allowed from the corresponding real class.
+  > Otherwise, you'll get an error.
+  >
+  {style="note"}
 
 **When do the changes take effect?**
 

docs/topics/native/native-c-interop.md

@@ -646,4 +646,55 @@ fun readData(fd: Int) {
 ```
 
 Here we use service function `usePinned`, which pins an object, executes block and unpins it on normal and
-exception paths.
+exception paths.
+
+### Forward declarations
+
+To import forward declarations, use the `cnames` package. For example, to import a `cstructName` forward declaration
+declared in a C library with a `library.package`, use a special forward declaration package:
+`import cnames.structs.cstructName`.
+
+To transfer objects between libraries, you need to make an explicit `as` cast to and from the corresponding C
+forward declaration. Consider two cinterop libraries, one that has a forward declaration of a struct and the other
+with an actual implementation:
+
+```C
+// First C library
+#include <stdio.h>
+
+typedef struct ForwardDeclaredStruct ForwardDeclaredStruct;
+
+void consumeStruct(ForwardDeclaredStruct* s) {
+    printf("Struct consumed\n");
+}
+```
+
+```C
+// Second C library
+// Header:
+#include <stdlib.h>
+
+typedef struct {
+    int data;
+} ForwardDeclaredStruct;
+
+// Implementation:
+ForwardDeclaredStruct* produceStruct() {
+    ForwardDeclaredStruct* s = malloc(sizeof(ForwardDeclaredStruct));
+    s->data = 42;
+    return s;
+}
+```
+
+To transfer objects between them, make the `as` cast in you Kotlin code:
+
+```kotlin
+// Kotlin code:
+fun test() {
+    consumeStruct(produceStruct() as cnames.structs.ForwardDeclaredStruct)
+}
+```
+
+> Casting is only allowed from the corresponding real class. Otherwise, you'll get an error.
+>
+{type="note"}

docs/topics/native/native-objc-interop.md

@@ -228,7 +228,11 @@ A Swift/Objective-C initializer is imported to Kotlin as constructors or as fact
 The latter happens with initializers declared in the Objective-C category or as a Swift extension,
 because Kotlin has no concept of extension constructors.
 
-Kotlin constructors are imported as initializers to Swift/Objective-C. 
+> Remember to expose Swift methods with `@objc` before importing Swift initializers to Kotlin.
+>
+{type="tip"}
+
+Kotlin constructors are imported as initializers to Swift/Objective-C.
 
 ### Setters
 
@@ -569,6 +573,56 @@ binaries.framework {
 }
 ```
 
+### Forward declarations
+
+To import forward declarations, use the `objcnames` package. For example, to import a `objcstructName` forward declaration
+declared in an Objective-C library with a `library.package`, use a special forward declaration package:
+`import objcnames.structs.objcstructName`.
+
+To transfer objects between libraries, you need to make an explicit `as` cast to and from the corresponding Objective-C
+forward declaration. Consider two objcinterop libraries, one that uses `objcnames.protocols.ForwardDeclaredProtocolProtocol`
+and the other that has an actual definition:
+
+```ObjC
+// First objcinterop library
+#import <Foundation/Foundation.h>
+
+@protocol ForwardDeclaredProtocol;
+
+NSString* consumeProtocol(id<ForwardDeclaredProtocol> s) {
+    return [NSString stringWithUTF8String:"Protocol"];
+}
+```
+
+```ObjC
+// Second objcinterop library
+// Header:
+#import <Foundation/Foundation.h>
+@protocol ForwardDeclaredProtocol
+@end
+// Implementation:
+@implementation ForwardDeclaredProtocolImpl : NSObject
+@end;
+
+id<ForwardDeclaredProtocol> produceProtocol() {
+    return [ForwardDeclaredProtocolImpl new];
+}
+```
+
+To transfer objects between them, make the `as` cast in you Kotlin code:
+
+```kotlin
+// Kotlin code:
+fun test() {
+    consumeStruct(produceStruct() as cnames.structs.ForwardDeclaredStruct)
+}
+```
+
+> The casting to `objcnames.protocols.ForwardDeclaredProtocolProtocol` is only allowed from the corresponding real class.
+> Otherwise, you'll get an error.
+>
+{type="note"}
+
 ## Casting between mapped types
 
 When writing Kotlin code, an object may need to be converted from a Kotlin type to the equivalent Swift/Objective-C type