Update docs for @Throws suspend fun

* Update docs for `@Throws suspend fun`.

Co-authored-by: Pavel Semyonov <42832629+p7nov@users.noreply.github.com>

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:` | | |
+| `suspend` -> | `completionHandler:` | | [note](#errors-and-exceptions) |
-| `@Throws` | `throws` | `error:(NSError**)error` | [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.

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")