feat(kmp): improve docs (#7024)

Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
Co-authored-by: Manoel Aranda Neto <marandaneto@gmail.com>
Co-authored-by: Shana Matthews <shana.l.matthews@gmail.com>

Author: 4 people

src/platform-includes/getting-started-install/kotlin-multiplatform.mdx

@@ -1,13 +1,3 @@
-### Prerequisites (Android)
-
-Android requires disabling auto-init to not clash with the ContentProvider, which auto-initializes the Sentry Android SDK. To do so, add the following to the AndroidManifest.xml file under your androidMain source set:
-
-```xml
-<application>
-    <meta-data android:name="io.sentry.auto-init" android:value="false" />
-</application>
-```
-
 To install the Kotlin Multiplatform SDK, you need to add the following to your `build.gradle.kts` file in your shared module:
 
 ```kotlin {filename:shared/build.gradle.kts}
@@ -16,20 +6,27 @@ repositories {
 }
 
 kotlin {
-  val commonMain by getting {
-    dependencies {
-      api("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}")
+  android()
+  iosX64()
+  iosArm64()
+  iosSimulatorArm64()
+
+  sourceSets {
+    val commonMain by getting {
+      dependencies {
+        implementation("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}")
+      }
     }
-  }
 
-  // Android target
-  val androidMain by getting {
-    dependsOn(commonMain)
-  }
+    // Android target
+    val androidMain by getting {
+      dependsOn(commonMain)
+    }
 
-  // Apple targets:
-  val iosMain by getting {
-    dependsOn(commonMain)
+    // Apple targets:
+    val iosMain by getting {
+      dependsOn(commonMain)
+    }
   }
 
   cocoapods {
@@ -41,7 +38,6 @@ kotlin {
 
     framework {
       baseName = "shared"
-      export("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}")
     }
   }
 }

src/platform-includes/getting-started-primer/kotlin-multiplatform.mdx

@@ -8,6 +8,6 @@ Sentry's Kotlin Multiplatform SDK builds on top of multiple Sentry SDKs, allowin
 
 <Note>
 
-This SDK is currently experimental.
+Kotlin Multiplatform requires using version **8.4.0** of the Sentry Cocoa SDK, specifically. Other versions, including newer ones, aren't guaranteed to work.
 
 </Note>

src/platforms/kotlin-multiplatform/common/install/cocoapods.mdx

@@ -0,0 +1,50 @@
+---
+title: Cocoapods
+description: "Learn about installing the Sentry Kotlin Multiplatform SDK with Cocoapods."
+---
+
+To install the Kotlin Multiplatform SDK and setup your Apple targets with Cocoapods, you need to add the following to your `build.gradle.kts` file in your shared module:
+
+<Note>
+  Kotlin Multiplatform requires using version **8.4.0** of the Sentry Cocoa SDK,
+  specifically. Other versions, including newer ones, aren't guaranteed to work.
+</Note>
+
+```kotlin {filename:shared/build.gradle.kts}
+repositories {
+    mavenCentral()
+}
+
+kotlin {
+  iosX64()
+  iosArm64()
+  iosSimulatorArm64()
+
+  sourceSets {
+    val commonMain by getting {
+      dependencies {
+        implementation("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}")
+      }
+    }
+
+    // Other targets...
+
+    // Apple targets:
+    val iosMain by getting {
+      dependsOn(commonMain)
+    }
+
+    cocoapods {
+      summary = "Some description for the Shared Module"
+      homepage = "Link to the Shared Module homepage"
+      ios.deploymentTarget = "14.1"
+      podfile = project.file("../iosApp/Podfile")
+      pod("Sentry", "~> 8.4.0")
+
+      framework {
+        baseName = "shared"
+      }
+    }
+  }
+}
+```

src/platforms/kotlin-multiplatform/common/install/index.mdx

@@ -0,0 +1,7 @@
+---
+title: Apple Installation Methods
+sidebar_order: 1
+description: "All the installation methods for the Apple platform."
+---
+
+<PageGrid />

src/platforms/kotlin-multiplatform/common/install/swift-package-manager.mdx

@@ -0,0 +1,60 @@
+---
+title: Swift Package Manager (SPM)
+description: "Learn about installing the Sentry Kotlin Multiplatform SDK with Swift Package Manager."
+---
+
+<Note>
+  Kotlin Multiplatform requires using version **8.4.0** of the Sentry Cocoa SDK,
+  specifically. Other versions, including newer ones, aren't guaranteed to work.
+</Note>
+
+Add the Sentry Cocoa SDK as a package in Xcode in your iOS app via **File > Add Packages**.
+Enter the Git repo URL in the search field:
+
+```text
+https://github.com/getsentry/sentry-cocoa.git
+```
+
+Define your dependency rule to have the exact version `8.4.0` and then click the "Add Package" button.
+
+Alternatively, if your project uses a `Package.swift` file to manage dependencies, you can specify the target with:
+
+```swift {tabTitle:Swift}
+.package(url: "https://github.com/getsentry/sentry-cocoa", from: "8.4.0"),
+```
+
+Next, install the Kotlin Multiplatform SDK and setup your Apple targets by adding the following to your `build.gradle.kts` file in your shared module:
+
+```kotlin {filename:shared/build.gradle.kts}
+repositories {
+    mavenCentral()
+}
+
+kotlin {
+  listOf(
+    iosX64(),
+    iosArm64(),
+    iosSimulatorArm64()
+  ).forEach {
+    it.binaries.framework {
+        baseName = "shared"
+        isStatic = true // currently available only as static framework
+    }
+  }
+
+  sourceSets {
+    val commonMain by getting {
+      dependencies {
+        implementation("io.sentry:sentry-kotlin-multiplatform:{{@inject packages.version('sentry.kotlin.kmp', '0.0.1-alpha.2') }}")
+      }
+    }
+
+    // Apple targets:
+    val iosMain by getting {
+      dependsOn(commonMain)
+    }
+
+    // Other targets...
+  }
+}
+```

src/platforms/kotlin-multiplatform/debug-symbols.mdx

@@ -0,0 +1,46 @@
+---
+title: Upload Debug Symbols
+sidebar_order: 1
+description: "Learn more about how to upload debug symbols in Sentry Kotlin Multiplatform."
+---
+
+To symbolicate your stacktraces, you need to provide debug information to Sentry.
+The symbolication process unscrambles the stacktraces to reveal the function, file names, and line numbers of the crash.
+
+## Apple
+
+For Apple applications please follow the iOS documentation on [Uploading Debug Symbols](/platforms/apple/guides/ios/dsym) to set up debug symbols upload.
+
+## Android
+
+### Gradle
+
+To upload ProGuard mapping files or Native debug bymbols via Gradle you need to install the [Sentry Android Gradle](/platforms/android/gradle) plugin:
+
+```kotlin {filename:androidApp/build.gradle.kts}
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+}
+
+plugins {
+    id("com.android.application")
+    id("io.sentry.android.gradle") version "{{@inject packages.version('sentry.java.android.gradle-plugin', '3.0.0') }}"
+}
+
+// Prevent Sentry dependencies from being included in the Android app through the AGP.
+sentry {
+  autoInstallation {
+    enabled.set(false)
+  }
+}
+```
+
+#### ProGuard/R8 & DexGuard
+
+Learn more in the Sentry Gradle Plugin docs for [ProGuard/R8 & DexGuard](/platforms/android/gradle/#proguardr8--dexguard).
+
+#### Native Debug Symbols and Sources
+
+You can find more information in the Sentry Gradle Plugin docs for [Native Debug Symbols and Sources](/platforms/android/gradle/#native-debug-symbols-and-sources).

src/platforms/kotlin-multiplatform/initialization-strategies.mdx

@@ -1,6 +1,6 @@
 ---
 title: Initialization Strategies
-sidebar_order: 0
+sidebar_order: 2
 description: "Strategies for initializing the Kotlin Multiplatform SDK."
 ---
 
@@ -24,12 +24,17 @@ import io.sentry.kotlin.multiplatform.Sentry
 
 // Application context is only needed for Android targets
 fun initializeSentry(context: Context?) {
-  Sentry.init(context) {
-    it.dsn = "___PUBLIC_DSN___"
+  if (context != null) {
+    Sentry.init(context) {
+      it.dsn = "___PUBLIC_DSN___"
+      // Add common configuration here
+    }
   }
 }
 ```
 
+Now you can use that shared function to initialize the SDK.
+
 ### Android
 
 ```kotlin {filename:MainActivity.kt}
@@ -44,7 +49,7 @@ class YourApplication : Application() {
 }
 ```
 
-### Cocoa/Apple
+### iOS
 
 ```swift {filename:AppDelegate.swift}
 import shared
@@ -62,25 +67,63 @@ func application(
 
 Platform-specific initializers allow for customization of the SDK's configuration options on a per-platform basis. This approach can be particularly useful when your SDK requires platform-specific functionality or performance optimizations.
 
-With platform-specific initializers, you can initialize the SDK directly in the target platform's codebase. This approach gives you the flexibility to fine-tune the SDK's behavior to meet the unique needs of each platform.
+This approach gives you the flexibility to fine-tune the SDK's behavior to meet the unique needs of each platform.
+
+### Common
+
+```kotlin {filename:commonMain/AppSetup.kt}
+import io.sentry.kotlin.multiplatform.Context
+
+expect fun initializeSentry(context: Context? = null)
+```
+
+### androidMain
+
+```kotlin {filename:androidMain/AppSetup.kt}
+import io.sentry.kotlin.multiplatform.Sentry
+import io.sentry.kotlin.multiplatform.Context
+
+actual fun initializeSentry(context: Context?) {
+  if (context != null) {
+    Sentry.init(context) {
+      it.dsn = "___PUBLIC_DSN___"
+      // Add Android-specific configuration here
+    }
+  }
+}
+```
+
+### iosMain
+
+```kotlin {filename:iosMain/AppSetup.kt}
+import io.sentry.kotlin.multiplatform.Sentry
+import io.sentry.kotlin.multiplatform.Context
+
+actual fun initializeSentry(context: Context?) {
+  Sentry.init {
+    it.dsn = "___PUBLIC_DSN___"
+    // Add iOS-specific configuration here
+  }
+}
+```
+
+Now you can use that shared function to initialize the SDK.
 
 ### Android
 
 ```kotlin {filename:MainActivity.kt}
-import io.sentry.kotlin.multiplatform.Sentry
+import your.kmp.app.initializeSentry
 
 class YourApplication : Application() {
   override fun onCreate() {
     super.onCreate()
       // Make sure to add the context!
-      Sentry.init(this) {
-        it.dsn = "___PUBLIC_DSN___"
-      }
+      initializeSentry(this)
    }
 }
 ```
 
-### Cocoa/Apple
+### iOS
 
 ```swift {filename:AppDelegate.swift}
 import shared
@@ -89,15 +132,13 @@ func application(
     _ application: UIApplication,
     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil
 ) -> Bool {
-    Sentry.shared.doInit() { options in
-      options.dsn = "___PUBLIC_DSN___"
-    }
+    AppSetupKt.initializeSentry(context = nil)
     return true
 }
 ```
 
 ## Hybrid Approach
 
-It's also possible to mix the two initialization strategies by creating custom `sourceSets` that only target specific platforms. This allows you to use a shared initializer for some platforms while utilizing platform-specific initializers for others.
+It's also possible to mix the two initialization strategies by creating [intermediate sourceSets](https://kotlinlang.org/docs/multiplatform-hierarchy.html) that only target specific platforms. This allows you to use a shared initializer for some platforms while utilizing platform-specific initializers for others.
 
 For example, you may choose to use a shared initializer for Android and iOS platforms, while using a platform-specific initializer for the watchOS and tvOS platform. This approach provides a balance between consistency and customization.