more docs

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

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<*>>()

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)