From 1b6695654bbb392f06ec52664bf6f1992b6f60eb Mon Sep 17 00:00:00 2001
From: alfredo-toledano <alfredo.toledano@allianzdirect.es>
Date: Sat, 30 Nov 2024 22:12:59 +0100
Subject: [PATCH] doc(docs.topics.native.cInterOperability): add notes

---
 docs/topics/native/native-c-interop.md | 86 +++++++++++++-------------
 1 file changed, 42 insertions(+), 44 deletions(-)

diff --git a/docs/topics/native/native-c-interop.md b/docs/topics/native/native-c-interop.md
index 20538f60958..fdaa54b3b08 100644
--- a/docs/topics/native/native-c-interop.md
+++ b/docs/topics/native/native-c-interop.md
@@ -1,60 +1,58 @@
 [//]: # (title: Interoperability with C)
 
-> The C libraries import is [Experimental](components-stability.md#stability-levels-explained).
-> All Kotlin declarations generated by the `cinterop` tool from C libraries
-> should have the `@ExperimentalForeignApi` annotation.
-> 
-> Native platform libraries shipped with Kotlin/Native (like Foundation, UIKit, and POSIX),
-> require opt-in only for some APIs. In such cases, you get an IDE warning.
-> 
-{type="warning"}
-
-Kotlin/Native follows the general tradition of Kotlin to provide excellent
-existing platform software interoperability. In the case of a native platform,
-the most important interoperability target is a C library. So Kotlin/Native
-comes with a `cinterop` tool, which can be used to quickly generate
-everything needed to interact with an external library.
-
-The following workflow is expected when interacting with the native library:
-1. Create a `.def` file describing what to include into bindings.
-2. Use the `cinterop` tool to produce Kotlin bindings.
-3. Run the Kotlin/Native compiler on an application to produce the final executable.
-
-The interoperability tool analyses C headers and produces a "natural" mapping of
-the types, functions, and constants into the Kotlin world. The generated stubs can be
-imported into an IDE for the purpose of code completion and navigation.
-
-Interoperability with Swift/Objective-C is provided too and covered in [Objective-C interop](native-objc-interop.md).
+* Kotlin/Native's software interoperability
+  * -- as good as -- Kotlin's software interoperability
+  * | ALL native platform,
+    * 👀C library == MOST important interoperability target👀
+      * -> Kotlin/Native -- comes with a -- `cinterop` tool
+    * Swift/Objective-C
+      * see [Objective-C interop](native-objc-interop.md)
+
+* `cinterop` tool
+  * allows
+    * generating everything needed -- to interact with an -- external library
+      * analyses C headers
+      * produces a "natural" mapping | Kotlin, of 
+        * types,
+        * functions,
+        * constants
+
+* workflow | interacting with the native library
+  1. Create a `.def` / describe what to include | bindings
+  2. Use `cinterop` tool -- to generate -- Kotlin bindings
+  3. Run the Kotlin/Native compiler | application -- to produce the -- final executable
 
 ## Platform libraries
 
-Note that in many cases there's no need to use custom interoperability library creation mechanisms described below,
-as for APIs available on the platform standardized bindings called [platform libraries](native-platform-libs.md)
-could be used. For example, POSIX on Linux/macOS platforms, Win32 on Windows platform, or Apple frameworks
-on macOS/iOS are available this way.
+* | MANY cases, NOT need to use custom interoperability library creation mechanisms
+  * Reason: 🧠you can use [platform libraries](native-platform-libs.md) 🧠
+* _Example:_ POSIX | Linux/macOS platforms, Win32 | Windows platform, Apple frameworks
+| macOS/iOS
 
 ## Simple example
 
-Install libgit2 and prepare stubs for the git library:
+* [install libgit2](https://github.com/libgit2/libgit2?tab=readme-ov-file#installation)
+  * TODO:
+* prepare stubs for the git library
 
-```bash
-cd samples/gitchurn
-../../dist/bin/cinterop -def src/nativeInterop/cinterop/libgit2.def \
- -compiler-option -I/usr/local/include -o libgit2
-```
+    ```bash
+    cd samples/gitchurn
+    ../../dist/bin/cinterop -def src/nativeInterop/cinterop/libgit2.def \
+     -compiler-option -I/usr/local/include -o libgit2
+    ```
 
-Compile the client:
+* compile the client
 
-```bash
-../../dist/bin/kotlinc src/gitChurnMain/kotlin \
- -library libgit2 -o GitChurn
-```
+    ```bash
+    ../../dist/bin/kotlinc src/gitChurnMain/kotlin \
+     -library libgit2 -o GitChurn
+    ```
 
-Run the client:
+* run the client
 
-```bash
-./GitChurn.kexe ../..
-```
+    ```bash
+    ./GitChurn.kexe ../..
+    ```
 
 ## Create bindings for a new library