diff --git a/OBJC_INTEROP.md b/OBJC_INTEROP.md index 4ea5339bcad..a623f497f2f 100644 --- a/OBJC_INTEROP.md +++ b/OBJC_INTEROP.md @@ -30,8 +30,8 @@ The table below shows how Kotlin concepts are mapped to Swift/Objective-C and vi | `constructor`/`create` | Initializer | Initializer | [note](#initializers) | | Property | Property | Property | [note](#top-level-functions-and-properties) [note](#setters)| | Method | Method | Method | [note](#top-level-functions-and-properties) [note](#method-names-translation) | -| `suspend` -> | `completionHandler:` | | | -| `@Throws` | `throws` | `error:(NSError**)error` | [note](#errors-and-exceptions) | +| `suspend` -> | `completionHandler:` | | [note](#errors-and-exceptions) | +| `@Throws fun` | `throws` | `error:(NSError**)error` | [note](#errors-and-exceptions) | | Extension | Extension | Category member | [note](#category-members) | | `companion` member <- | Class method or property | Class method or property | | | `null` | `nil` | `nil` | | @@ -133,15 +133,20 @@ Swift has only checked errors. So if Swift or Objective-C code calls a Kotlin me which throws an exception to be handled, then the Kotlin method should be marked with a `@Throws` annotation specifying a list of "expected" exception classes. -When compiling to Objective-C/Swift framework, functions having or inheriting +When compiling to Objective-C/Swift framework, non-`suspend` functions having or inheriting `@Throws` annotation are represented as `NSError*`-producing methods in Objective-C -and as `throws` methods in Swift. +and as `throws` methods in Swift. Representations for `suspend` functions always have +`NSError*`/`Error` parameter in completion handler. When Kotlin function called from Swift/Objective-C code throws an exception which is an instance of one of the `@Throws`-specified classes or their subclasses, it is propagated as `NSError`. Other Kotlin exceptions reaching Swift/Objective-C are considered unhandled and cause program termination. +`suspend` functions without `@Throws` propagate only +`CancellationException` as `NSError`. Non-`suspend` functions without `@Throws` +don't propagate Kotlin exceptions at all. + Note that the opposite reversed translation is not implemented yet: Swift/Objective-C error-throwing methods aren't imported to Kotlin as exception-throwing. diff --git a/runtime/src/main/kotlin/kotlin/Annotations.kt b/runtime/src/main/kotlin/kotlin/Annotations.kt index 2a908fb2ce2..970697e9441 100644 --- a/runtime/src/main/kotlin/kotlin/Annotations.kt +++ b/runtime/src/main/kotlin/kotlin/Annotations.kt @@ -154,15 +154,20 @@ public annotation class PublishedApi /** * This annotation indicates what exceptions should be declared by a function when compiled to a platform method. * - * When compiling to Objective-C/Swift framework, functions having or inheriting + * When compiling to Objective-C/Swift framework, non-`suspend` functions having or inheriting * this annotation are represented as `NSError*`-producing methods in Objective-C - * and as `throws` methods in Swift. + * and as `throws` methods in Swift. Representations for `suspend` functions always have + * `NSError*`/`Error` parameter in completion handler * * When Kotlin function called from Swift/Objective-C code throws an exception * which is an instance of one of the [exceptionClasses] or their subclasses, * it is propagated as `NSError`. Other Kotlin exceptions reaching Swift/Objective-C * are considered unhandled and cause program termination. * + * Note: `suspend` functions without `@Throws` propagate only + * [kotlin.coroutines.cancellation.CancellationException] as `NSError`. + * Non-`suspend` functions without `@Throws` don't propagate Kotlin exceptions at all. + * * @property exceptionClasses the list of checked exception classes that may be thrown by the function. */ @SinceKotlin("1.4")