@Throws For Checked Exceptions

## Background: checked vs unchecked exceptions In **Java**, exceptions are split into two groups. **Checked** exceptions (subtypes of `Exception` that are not `RuntimeException`, e.g. `IOException`) must be either caught with `try/catch` or declared with a `throws` clause on the method — the Java compiler enforces this. **Unchecked** exceptions (`RuntimeException` and `Error` subtypes) need no declaration. **Kotlin has no checked exceptions at all.** Every exception is treated like an unchecked one: you are never *required* to catch or declare anything. This is a deliberate language decision. ## The interop problem When Kotlin compiles a function, the generated JVM method has **no `throws` clause** by default. For Kotlin callers this is invisible and harmless. But a **Java** caller sees a method that declares it throws nothing. If the Java code writes: ```java try { kotlinReadFile(); } catch (IOException e) { ... } // compile error in Java ``` the Java compiler rejects it with *"exception IOException is never thrown in the corresponding try block"*, because the method signature does not declare `IOException`. ## What `@Throws` does `@Throws(vararg exceptionClasses: KClass<out Throwable>)` instructs the Kotlin compiler to write those exception types into the **`throws` clause of the generated JVM method**. It does **not** change runtime behavior, does not wrap anything, and does not affect Kotlin callers — it only edits the method's bytecode signature so Java sees a normal checked-exception declaration. ```kotlin import java.io.IOException @Throws(IOException::class) fun readConfig(path: String): String { // may throw IOException at runtime return java.io.File(path).readText() } ``` The generated method becomes the Java-visible `String readConfig(String) throws IOException`. ## Key facts - It accepts a **vararg** of `KClass` references, so you can list several: `@Throws(IOException::class, TimeoutException::class)`. - It is **interop-only**: Kotlin callers gain nothing and are still not forced to handle the exception. - It does not make Kotlin enforce anything — the function can throw the listed types or not; the annotation is purely a signature hint. - The fully qualified name is `kotlin.Throws` (in package `kotlin`, auto-imported). ## When to use it Use it on Kotlin functions that are part of a **public API consumed from Java** and that legitimately throw a checked exception Java callers should handle — e.g. I/O, parsing, or `Closeable.close()`. If your code is Kotlin-only, you almost never need it.