Add kdoc to binding/coroutineBinding

Author: michaelbull

kotlin-result-coroutines/src/commonMain/kotlin/com/github/michaelbull/result/coroutines/CoroutineBinding.kt

@@ -64,6 +64,29 @@ public class BindingCancellationException : CancellationException(null as String
 
 @BindingDsl
 public interface CoroutineBindingScope<E> : CoroutineScope {
+
+    /**
+     * Unwraps this [Result], returning the [value][Result.value] if [Ok], or short-circuiting
+     * the enclosing [coroutineBinding] block with the [error][Result.error] if [Err].
+     *
+     * Unlike [BindingScope.bind][com.github.michaelbull.result.BindingScope.bind], this
+     * function also [cancels][CoroutineScope.cancel] the enclosing [CoroutineScope], cancelling
+     * all other child coroutines.
+     *
+     * This is functionally equivalent to Rust's
+     * [`?` operator](https://doc.rust-lang.org/std/result/index.html#the-question-mark-operator-).
+     *
+     * ```
+     * suspend fun provideX(): Result<Int, ExampleErr> { ... }
+     * suspend fun provideY(): Result<Int, ExampleErr> { ... }
+     *
+     * val result: Result<Int, ExampleErr> = coroutineBinding {
+     *   val x = provideX().bind()
+     *   val y = provideY().bind()
+     *   x + y
+     * }
+     * ```
+     */
     public suspend fun <V> Result<V, E>.bind(): V
 }
 

kotlin-result/src/commonMain/kotlin/com/github/michaelbull/result/Binding.kt

@@ -46,6 +46,25 @@ public expect class BindingException() : Exception
 
 @BindingDsl
 public interface BindingScope<E> {
+
+    /**
+     * Unwraps this [Result], returning the [value][Result.value] if [Ok], or short-circuiting
+     * the enclosing [binding] block with the [error][Result.error] if [Err].
+     *
+     * This is functionally equivalent to Rust's
+     * [`?` operator](https://doc.rust-lang.org/std/result/index.html#the-question-mark-operator-).
+     *
+     * ```
+     * fun provideX(): Result<Int, ExampleErr> { ... }
+     * fun provideY(): Result<Int, ExampleErr> { ... }
+     *
+     * val result: Result<Int, ExampleErr> = binding {
+     *   val x = provideX().bind()
+     *   val y = provideY().bind()
+     *   x + y
+     * }
+     * ```
+     */
     public fun <V> Result<V, E>.bind(): V
 }