feat(apple): Add docs for Swift Error description (#6805)

Sentry Cocoa 8.7.0 contains improvements for Swift error descriptions. This PR adds the docs for this feature. Co-authored-by: Shana Matthews <[email protected]> Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
getsentry · May 10, 2023 · 3894b0d · 3894b0d
1 parent 1f2e2b4
commit 3894b0d
Showing 1 changed file with 31 additions and 10 deletions.
diff --git a/src/platform-includes/capture-error/apple.mdx b/src/platform-includes/capture-error/apple.mdx
@@ -21,27 +21,36 @@ if (error) {
 }
 ```
 
-<PlatformSection supported={["apple.macos"]}>
+### Swift Errors
 
-## Capturing Uncaught Exceptions in macOS
+For Swift Errors conforming to the [Error Protocol](https://developer.apple.com/documentation/swift/error) the SDK sends the domain, code and the description of the Swift error.
+For older versions of the SDK, prior to [sentry-cocoa 8.7.0](https://github.com/getsentry/sentry-cocoa/blob/main/CHANGELOG.md#870) the SDK only sends the domain and error code.
 
-By default, macOS applications do not crash whenever an uncaught exception occurs. To enable this with Sentry:
+```Swift
+enum LoginError: Error {
+    case wrongUser(id: String)
+    case wrongPassword
+}
 
-1. Open the application's `Info.plist` file
-2. Search for `Principal class` (the entry is expected to be `NSApplication`)
-3. Replace `NSApplication` with `SentryCrashExceptionApplication`
+SentrySDK.capture(error: LoginError.wrongUser("12345678"))
+```
 
-</PlatformSection>
+For the Swift error above Sentry displays:
 
-## Customizing Error Descriptions
+| sentry-cocoa SDK | Title        | Description                           |
+| ---------------- | ------------ | ------------------------------------- |
+| Since 8.7.0      | `LoginError` | `wrongUser(id: "12345678") (Code: 1)` |
+| Before 8.7.0     | `LoginError` | `Code: 1`                             |
+
+### Customizing Error Descriptions
 
 This feature is available on [sentry-cocoa 7.25.0](https://github.com/getsentry/sentry-cocoa/blob/master/CHANGELOG.md#7250) and above.
 
-Sentry will display the error code in the error description field by default. For custom error types, you may want to provide a custom description to make it easier to identify the error in the _Issues_ page. For `NSError` values, this can be done by adding a description to the `userInfo` dictionary with the key `NSDebugDescriptionErrorKey`.
+You may want to provide a custom description to make identifying the error in the **Issues** page easier. For `NSError` values, you can do this by adding a description to the `userInfo` dictionary with the key `NSDebugDescriptionErrorKey`.
 
 Sentry will group errors based on the error domain and code, and by enum value for Swift enum types, so customizing error descriptions won’t impact grouping.
 
-This can be particularly useful for Swift enum error types that conform to `Error`, where the error code can be hard to match with an enum case. To customize the description for Swift `Error` types, you should conform to the `CustomNSError` protocol and return a user info dictionary:
+To customize the description for Swift `Error` types, you should conform to the `CustomNSError` protocol and return a user info dictionary:
 
 ```swift {tabTitle:Swift}
 enum MyCustomError: Error {
@@ -64,3 +73,15 @@ extension MyCustomError: CustomNSError {
     }
 }
 ```
+
+<PlatformSection supported={["apple.macos"]}>
+
+## Capturing Uncaught Exceptions in macOS
+
+By default, macOS applications do not crash whenever an uncaught exception occurs. To enable this with Sentry:
+
+1. Open the application's `Info.plist` file
+2. Search for `Principal class` (the entry is expected to be `NSApplication`)
+3. Replace `NSApplication` with `SentryCrashExceptionApplication`
+
+</PlatformSection>