From 2e4f551e8e9450e26306960a849d2a2e23308353 Mon Sep 17 00:00:00 2001
From: sergeych <real.sergeych@gmail.com>
Date: Sun, 11 Aug 2024 16:28:09 +0200
Subject: [PATCH] more docs

---
 README.md                                         |  6 ++++--
 .../net/sergeych/kiloparsec/LocalInterface.kt     | 15 +++++++++++++--
 .../net/sergeych/kiloparsec/RemoteInterface.kt    | 11 ++++++++++-
 3 files changed, 27 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 5005847..c8f3f98 100644
--- a/README.md
+++ b/README.md
@@ -33,11 +33,13 @@ format. The format from 0.3.0 onwards is supposed to keep compatible.
 - JS (browser and nodeJS)
 - JVM (android, macos, windows, linx, everywhere where JRE is installed)
 
-## TCP/IP transport
+## TCP/IP and UDP transports
 
-It is the fastest based on async socket implementation of ktor client. It works everywhere but JS target as
+These are the fastest based on async socket implementation of ktor client. They works everywhere but JS target as
 there is currently no widely adopted sockets for browser javascript.
 
+While UDP is faster than TCP/IP, it is less reliable, especially with commands and return values that serializes to more than 240 bytes approx, and has no retransmission facilities (use TCP!). UDP though shines when all you need is to [push](https://code.sergeych.net/docs/kiloparsec/kiloparsec/net.sergeych.kiloparsec/-remote-interface/push.html) with little or no data in it.
+
 ## Websock server
 
 While it is much slower than pure TCP, it is still faster than any http-based transport. It uses binary frames based on
diff --git a/src/commonMain/kotlin/net/sergeych/kiloparsec/LocalInterface.kt b/src/commonMain/kotlin/net/sergeych/kiloparsec/LocalInterface.kt
index fe16b8e..f28ff8b 100644
--- a/src/commonMain/kotlin/net/sergeych/kiloparsec/LocalInterface.kt
+++ b/src/commonMain/kotlin/net/sergeych/kiloparsec/LocalInterface.kt
@@ -74,7 +74,11 @@ open class LocalInterface<S> : Loggable by LogTag("LocalInterface${idCounter.inc
     private val errorByClass = mutableMapOf<KClass<*>, String>()
     private val errorBuilder = mutableMapOf<String, (String, UByteArray?) -> Throwable>()
 
-    fun <T : Throwable> registerError(
+    /**
+     * Register exception for automatic transmission over the kiloparsec connection using its [klass]
+     * and possibly override code. In most cases it is simpler to use [registerError].
+     */
+    fun <T : Throwable> registerErrorClass(
         klass: KClass<T>, code: String = klass.simpleName!!,
         exceptionBuilder: (String, UByteArray?) -> T,
     ) {
@@ -82,10 +86,17 @@ open class LocalInterface<S> : Loggable by LogTag("LocalInterface${idCounter.inc
         errorBuilder[code] = exceptionBuilder
     }
 
+    /**
+     * Register an exception to be transmitted automatically over the kiloparsec connection.
+     * Example:
+     * ```kotlin
+     * localInterface.registerError { IllegalArgumentException(it) }
+     * ```
+     */
     inline fun <reified T : Throwable> registerError(
         noinline exceptionBuilder: (String) -> T,
     ) {
-        registerError(T::class) { msg, _ -> exceptionBuilder(msg) }
+        registerErrorClass(T::class) { msg, _ -> exceptionBuilder(msg) }
     }
 
     val errorProviders = mutableListOf<LocalInterface<*>>()
diff --git a/src/commonMain/kotlin/net/sergeych/kiloparsec/RemoteInterface.kt b/src/commonMain/kotlin/net/sergeych/kiloparsec/RemoteInterface.kt
index c250f1a..b74c712 100644
--- a/src/commonMain/kotlin/net/sergeych/kiloparsec/RemoteInterface.kt
+++ b/src/commonMain/kotlin/net/sergeych/kiloparsec/RemoteInterface.kt
@@ -47,7 +47,14 @@ interface RemoteInterface {
     suspend fun <R> call(cmd: Command<Unit, R>): R = call(cmd, Unit)
 
     /**
-     * Call the remote procedure with specified args and return its result
+     * Call the remote procedure with specified [args] and return its result of type [R]. The calling coroutine
+     * suspends until the request is performed on the remote side and the result value (also `Unit`) will be received.
+     *
+     * When it is not necessary to wait for the return value and/or command execution, it is recommended to
+     * use [push] instead.
+     *
+     *  @throws RemoteException if the execution caused exception on the remote size
+     *  @throws Exception for registered exceptions, see [LocalInterface.registerError], etc.
      */
     suspend fun <A, R> call(cmd: Command<A, R>, args: A): R
 
@@ -55,6 +62,8 @@ interface RemoteInterface {
      * Push the notification without waiting for reception or processing.
      * It returns immediately after sending data to the transport (e.g., to the network).
      * Use [call] if it is necessary to wait until the command will be received and processed by the remote.
+     *
+     * Push is onlu available for commands without returned value.
      */
     suspend fun <A> push(cmd: Command<A, Unit>, args: A)