Update docs and v0.8.1

Author: kpgalligan

README.md

@@ -4,22 +4,12 @@ Thin library that provides symbolicated crash reports for Kotlin code on iOS. Su
 
 To use crash reporting with general logging support, check out [Kermit](https://github.com/touchlab/Kermit/).
 
+If you're wondering *why* you need this library, please see [the problem](THE_PROBLEM.md).
+
 > ## Subscribe!
 >
 > We build solutions that get teams started smoothly with Kotlin Multiplatform Mobile and ensure their success in production. Join our community to learn how your peers are adopting KMM.
- [Sign up here](https://go.touchlab.co/newsletter-gh)!
-
-## The Problem
-
-Crash reporter clients on iOS take the stack of active threads at the moment of crash. Kotlin on iOS, like Kotlin on the JVM, bubbles exceptions up until they are caught or reach the top of the call stack, at which point an unhandled exception hook is called. Because this differs from how iOS works, the crash report shows the point at which we call into Kotlin from Swift/Objc.
-
-<img src="kotlinabort.png" alt="Abort report" style="zoom:50%;" />
-
-We want to get the caught exception and record that instead:
-
-<img src="kotlinlines.png" alt="Abort report" style="zoom: 67%;" />
-
-That's what this library is for.
+> [Sign up here](https://go.touchlab.co/newsletter-gh)!
 
 ## Crashlytics Usage
 
@@ -33,19 +23,23 @@ val commonMain by sourceSets.getting {
 }
 ```
 
-For both Android and iOS, you must call the following:
+The library by default has noop implementations of the crash logging calls. This is because in test situations you generally don't want to interact with the crash logging. On iOS specifically, this will allow you to run tests without needing to link against the Crashlytics runtime library.
+
+As a result, in the live app you need to initialize CrashKiOS. For both Android and iOS, you must call the following:
 
 ```kotlin
 enableCrashlytics()
 ```
 
+You sould generally do this as part of app initialization, after you make the calls to start Crashlytics itself.
+
 On iOS, you should also set the unhandled exception hook:
 
 ```kotlin
 setCrashlyticsUnhandledExceptionHook()
 ```
 
-Once initialized, you call methods on `CrashlyticsKotlin`
+Once initialized, you call methods on `CrashlyticsKotlin`, from common code or platform-specific code.
 
 ```kotlin
 CrashlyticsKotlin.logMessage("Some message")
@@ -75,14 +69,18 @@ Undefined symbols for architecture x86_64:
 ld: symbol(s) not found for architecture x86_64
 ```
 
-To resolve this, you should tell the linker that Crashlytics will be added later. To do that, add a Gradle plugin that will configure your linker settings.
+To resolve this, you should tell the linker that Crashlytics will be added later. You can do that directly, or you can use our Gradle plugin. It will find all Xcode Frameworks being built by Kotlin and add the necessary linker arguments.
 
 ```kotlin
 plugins {
   id("co.touchlab.crashkios.crashlyticslink") version "x.y.z"
 }
 ```
 
+### Crashlytics Sample
+
+See [samples/sample-crashlytics](samples/sample-crashlytics).
+
 ## Bugsnag Usage
 
 Add the dependency.
@@ -95,7 +93,19 @@ val commonMain by sourceSets.getting {
 }
 ```
 
-Bugsnag is somewhat more complex than Crashlytics. On startup, on iOS only, the library needs to suppress an extra error report from being sent. That requires some extra calls on iOS, or you can use a helper function that will handle the calls.
+The library by default has noop implementations of the crash logging calls. This is because in test situations you generally don't want to interact with the crash logging. On iOS specifically, this will allow you to run tests without needing to link against the Bugsnag runtime library.
+
+As a result, in the live app you need to initialize CrashKiOS. For both Android and iOS, you must call the following:
+
+```kotlin
+enableBugsnag()
+```
+
+You sould generally do this as part of app initialization, after you make the calls to start Bugsnag itself.
+
+### iOS Only
+
+Bugsnag is somewhat more complex than Crashlytics on iOS. On startup, the library needs to suppress an extra error report from being sent. That requires some extra calls, or you can use a helper function that will handle everything.
 
 The detailed calls you need to make are the following:
 
@@ -105,6 +115,8 @@ In the iOS init, before starting Bugsnag, you need to call `configureBugsnag` wi
 let config = BugsnagConfiguration.loadConfig()
 ```
 
+#### Option 1: Manual Calls
+
 Call `configureBugsnag` with that config. This *must* be called before starting Bugsnag.
 
 ```swift
@@ -123,20 +135,26 @@ Then set the default exception handler hook
 BugsnagConfigKt.setBugsnagUnhandledExceptionHook()
 ```
 
-Alternatively, call the helper function
+If you haven't done so, call:
 
 ```swift
-BugsnagConfigKt.startBugsnag(config: config)
+BugsnagConfigKt.enableBugsnag()
 ```
 
-That function calls `configureBugsnag`, `Bugsnag.start`, and `setBugsnagUnhandledExceptionHook`.
 
-For both Android and iOS, you must call the following:
 
-```kotlin
-enableBugsnag()
+#### Option 2: Helper Calls
+
+You can call a single function that performs the 4 steps above.
+
+```swift
+BugsnagConfigKt.startBugsnag(config: config)
 ```
 
+That function calls `configureBugsnag`, `Bugsnag.start`, `setBugsnagUnhandledExceptionHook`, and `enableBugsnag()`.
+
+### Using the Library
+
 Once initialized, you call methods on `BugsnagKotlin`
 
 ```kotlin
@@ -148,7 +166,7 @@ BugsnagKotlin.setCustomValue("someKey", "someValue")
 
 ### Testing
 
-You test code should not call `enableBugsnag()`. Before calling `enableBugsnag()`, calls to `BugsnagKotlin` are all no-ops. Also, on iOS, avoiding `enableBugsnag()` means you don't need to worry about Bugsnag linker issues.
+Your test code should not call `enableBugsnag()`. Before calling `enableBugsnag()`, calls to `BugsnagKotlin` are all no-ops. Also, on iOS, avoiding `enableBugsnag()` means you don't need to worry about Bugsnag linker issues.
 
 ### Linking
 
@@ -168,14 +186,18 @@ Undefined symbols for architecture x86_64:
 ld: symbol(s) not found for architecture x86_64
 ```
 
-To resolve this, you should tell the linker that Bugsnag will be added later. To do that, add a Gradle plugin that will configure your linker settings.
+To resolve this, you should tell the linker that Bugsnag will be added later. You can do that directly, or you can use our Gradle plugin. It will find all Xcode Frameworks being built by Kotlin and add the necessary linker arguments.
 
 ```kotlin
 plugins {
   id("co.touchlab.crashkios.bugsnaglink") version "x.y.z"
 }
 ```
 
+### Bugsnag Sample
+
+See [samples/sample-bugsnag](samples/sample-bugsnag).
+
 ## NSExceptionKt
 
 CrashKiOS and Kermit previously created 2 reports on a crash because none of the crash reporting clients had an obvious way to do one. [Rick Clephas](https://github.com/rickclephas) has done some excellent work figuring that out with [NSExceptionKt](https://github.com/rickclephas/NSExceptionKt). CrashKiOS now uses part of that library as a base and we've merged the cinterop from Kermit and NSExeptionKt to handle crashes as well as breadcrumb values and log statements.

THE_PROBLEM.md

@@ -0,0 +1,11 @@
+## The Problem
+
+Crash reporter clients on iOS take the stack of active threads at the moment of crash. Kotlin on iOS, like Kotlin on the JVM, bubbles exceptions up until they are caught or reach the top of the call stack, at which point an unhandled exception hook is called. Because this differs from how iOS works, the crash report shows the point at which we call into Kotlin from Swift/Objc.
+
+<img src="kotlinabort.png" alt="Abort report" style="zoom:50%;" />
+
+We want to get the caught exception and record that instead:
+
+<img src="kotlinlines.png" alt="Abort report" style="zoom: 67%;" />
+
+That's what this library is for.

bugsnag/src/darwinMain/kotlin/co/touchlab/crashkios/bugsnag/BugsnagConfig.kt

@@ -9,6 +9,7 @@ public fun startBugsnag(config: BugsnagConfiguration){
     configureBugsnag(config)
     Bugsnag.startWithConfiguration(config)
     setBugsnagUnhandledExceptionHook()
+    enableBugsnag()
 }
 
 /**

gradle.properties

@@ -6,7 +6,7 @@ kotlin.code.style=official
 SONATYPE_HOST=DEFAULT
 RELEASE_SIGNING_ENABLED=true
 GROUP=co.touchlab.crashkios
-VERSION_NAME=0.8.0
+VERSION_NAME=0.8.1
 NSEXCEPTION_KT_VERSION=0.1.1
 KOTLIN_VERSION=1.7.20
 BUGSNAG_ANDROID_VERSION=5.28.1

samples/sample-bugsnag/app/src/main/java/co/touchlab/crashkiossamplecrashlog/MainActivity.kt

@@ -20,7 +20,7 @@ import com.bugsnag.android.Bugsnag
 class MainActivity : AppCompatActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
-        Bugsnag.start(this)
+
         val binding = ActivityMainBinding.inflate(layoutInflater)
         setContentView(binding.root)
 

samples/sample-bugsnag/app/src/main/java/co/touchlab/crashkiossamplecrashlog/SampleApp.kt

@@ -18,6 +18,7 @@ class SampleApp : Application() {
     override fun onCreate() {
         super.onCreate()
 
+        Bugsnag.start(this)
         enableBugsnag()
     }
 }