Update API docs

Author: Mr3zee

core/src/commonMain/kotlin/kotlinx/rpc/RpcCall.kt

@@ -7,12 +7,12 @@ package kotlinx.rpc
 import kotlinx.rpc.descriptor.RpcServiceDescriptor
 
 /**
- * Represents a method or field call of an RPC service.
+ * Represents a method call from an RPC service.
  *
  * @property descriptor [RpcServiceDescriptor] of a service that made the call.
- * @property callableName The name of the callable. Can be the name of the method or field.
+ * @property callableName The name of the method being called.
  * @property data The data for the call.
- * @property serviceId id of the service, that made the call.
+ * @property serviceId The id of the service that made the call.
  */
 public data class RpcCall(
     val descriptor: RpcServiceDescriptor<*>,

core/src/commonMain/kotlin/kotlinx/rpc/RpcClient.kt

@@ -4,13 +4,11 @@
 
 package kotlinx.rpc
 
-import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.flow.Flow
 
 /**
  * [RpcClient] represents an abstraction of an RPC client, that can handle requests from several RPC services,
  * transform them, send to the server and handle responses and errors.
- * [CoroutineScope] defines the lifetime of the client.
  */
 public interface RpcClient {
     /**
@@ -19,7 +17,7 @@ public interface RpcClient {
      * @param T type of the result
      * @param call an object that contains all required information about the called method,
      * that is needed to route it properly to the server.
-     * @return actual result of the call, for example, data from the server.
+     * @return result of the call, for example, data from the server.
      */
     public suspend fun <T> call(call: RpcCall): T
 
@@ -30,7 +28,7 @@ public interface RpcClient {
      * @param T type of the result
      * @param call an object that contains all required information about the called method,
      * that is needed to route it properly to the server.
-     * @return the actual result of the call, for example, data from the server
+     * @return result of the call, for example, data from the server
      */
     public fun <T> callServerStreaming(call: RpcCall): Flow<T>
 }

core/src/commonMain/kotlin/kotlinx/rpc/RpcServer.kt

@@ -13,20 +13,32 @@ import kotlin.reflect.KClass
  */
 public interface RpcServer {
     /**
-     * Registers new service to the server. Server will route all designated messages to it.
+     * Registers new service. Server will route all designated messages to it.
      * Service of any type should be unique on the server, but RpcServer doesn't specify the actual retention policy.
      *
      * @param Service the exact type of the server to be registered.
-     * For example, for service with `MyService` interface and `MyServiceImpl` implementation,
-     * type `MyService` should be specified explicitly.
+     * For example, for a service with `MyService` interface and `MyServiceImpl` implementation
+     * the type `MyService` should be specified explicitly.
      * @param serviceKClass [KClass] of the [Service].
      * @param serviceFactory function that produces the actual implementation of the service that will handle the calls.
+     *
+     * @see kotlinx.rpc.annotations.CheckedTypeAnnotation
      */
     public fun <@Rpc Service : Any> registerService(
         serviceKClass: KClass<Service>,
         serviceFactory: () -> Service,
     )
 
+    /**
+     * Deregisters a service. Server will stop routing messages to it.
+     *
+     * @param Service the exact type of the server to be deregistered, the same one that was used for registration.
+     * For example, for a service with `MyService` interface and `MyServiceImpl` implementation
+     * the type `MyService` should be specified explicitly.
+     * @param serviceKClass [KClass] of the [Service].
+     *
+     * @see kotlinx.rpc.annotations.CheckedTypeAnnotation
+     */
     public fun <@Rpc Service : Any> deregisterService(
         serviceKClass: KClass<Service>,
     )
@@ -37,9 +49,11 @@ public interface RpcServer {
  * Service of any type should be unique on the server, but RpcServer doesn't specify the actual retention policy.
  *
  * @param Service the exact type of the server to be registered.
- * For example, for service with `MyService` interface and `MyServiceImpl` implementation,
- * type `MyService` should be specified explicitly.
+ * For example, for a service with `MyService` interface and `MyServiceImpl` implementation
+ * the type `MyService` should be specified explicitly.
  * @param serviceFactory function that produces the actual implementation of the service that will handle the calls.
+ *
+ * @see kotlinx.rpc.annotations.CheckedTypeAnnotation
  */
 public inline fun <@Rpc reified Service : Any> RpcServer.registerService(
     noinline serviceFactory: () -> Service,

core/src/commonMain/kotlin/kotlinx/rpc/annotations/CheckedTypeAnnotation.kt

@@ -5,8 +5,11 @@
 package kotlinx.rpc.annotations
 
 /**
- * Marks an annotation as a one that marks
- * a type argument as a one that requires its resolved type to be annotated this annotation.
+ * Meta annotation.
+ * Used to perform [annotation type-safety](https://kotlin.github.io/kotlinx-rpc/annotation-type-safety.html) checks.
+ *
+ * When an annotation class (for example, `@X`) is marked with `@CheckedTypeAnnotation` -
+ * Any other type can be marked with `@X` to perform safety checks on type parameters that are also marked with `@X`.
  *
  * Example:
  * ```kotlin

core/src/commonMain/kotlin/kotlinx/rpc/annotations/Rpc.kt

@@ -8,18 +8,24 @@ package kotlinx.rpc.annotations
  * Every [Rpc] annotated interface will have a code generation process run on it,
  * making the interface effectively usable for RPC calls.
  *
- * Example usage:
+ * Example usage.
+ *
+ * Define an interface and mark it with `@Rpc`.
+ * Compiler plugin will ensure that all declarations inside the interface are valid.
  * ```kotlin
- * // common code
  * @Rpc
  * interface MyService {
  *    suspend fun sayHello(firstName: String, lastName: String, age: Int): String
  * }
- * // client code
+ * ```
+ * On the client side use [kotlinx.rpc.RpcClient] to get a generated instance of the service, and use it to make calls:
+ * ```kotlin
  * val rpcClient: RpcClient
  * val myService = rpcClient.withService<MyService>()
  * val greetingFromServer = myService.sayHello("Alex", "Smith", 35)
- * // server code
+ * ```
+ * On the server side, define an implementation of this interface and register it on an [kotlinx.rpc.RpcServer]:
+ * ```kotlin
  * class MyServiceImpl : MyService {
  *     override suspend fun sayHello(firstName: String, lastName: String, age: Int): String {
  *         return "Hello, $firstName $lastName, of age $age. I am your server!"
@@ -28,6 +34,11 @@ package kotlinx.rpc.annotations
  * val server: RpcServer
  * server.registerService<MyService> { MyServiceImpl() }
  * ```
+ *
+ * @see kotlinx.rpc.RpcClient
+ * @see kotlinx.rpc.RpcServer
+ * @see CheckedTypeAnnotation
+ * @see kotlinx.rpc.withService
  */
 @CheckedTypeAnnotation
 @Target(AnnotationTarget.CLASS, AnnotationTarget.ANNOTATION_CLASS, AnnotationTarget.TYPE_PARAMETER)

core/src/commonMain/kotlin/kotlinx/rpc/withService.kt

@@ -12,21 +12,25 @@ import kotlin.reflect.KClass
 import kotlin.reflect.KType
 
 /**
- * Creates instance of the generated service [T], that is able to communicate with server using [RpcClient].
+ * Creates an instance of the generated service [T], that is able to communicate with a server using this [RpcClient].
  *
  * @param T the exact type of the service to be created.
  * @return instance of the generated service.
+ *
+ * @see kotlinx.rpc.annotations.CheckedTypeAnnotation
  */
 public inline fun <@Rpc reified T : Any> RpcClient.withService(): T {
     return withService(T::class)
 }
 
 /**
- * Creates instance of the generated service [T], that is able to communicate with server using [RpcClient].
+ * Creates an instance of the generated service [T], that is able to communicate with a server using this [RpcClient].
  *
  * @param T the exact type of the service to be created.
  * @param serviceKType [KType] of the service to be created.
  * @return instance of the generated service.
+ *
+ * @see kotlinx.rpc.annotations.CheckedTypeAnnotation
  */
 public fun <@Rpc T : Any> RpcClient.withService(serviceKType: KType): T {
     return withService(serviceKType.rpcInternalKClass())
@@ -39,11 +43,13 @@ public fun <@Rpc T : Any> RpcClient.withService(serviceKType: KType): T {
 private val SERVICE_ID = atomic(0L)
 
 /**
- * Creates instance of the generated service [T], that is able to communicate with server using [RpcClient].
+ * Creates an instance of the generated service [T], that is able to communicate with a server using this [RpcClient].
  *
  * @param T the exact type of the service to be created.
  * @param serviceKClass [KClass] of the service to be created.
  * @return instance of the generated service.
+ *
+ * @see kotlinx.rpc.annotations.CheckedTypeAnnotation
  */
 public fun <@Rpc T : Any> RpcClient.withService(serviceKClass: KClass<T>): T {
     val descriptor = serviceDescriptorOf(serviceKClass)

krpc/krpc-client/src/commonMain/kotlin/kotlinx/rpc/krpc/client/KrpcClient.kt

@@ -37,36 +37,59 @@ import kotlin.coroutines.cancellation.CancellationException
 import kotlin.properties.Delegates
 
 /**
- * Default implementation of [RpcClient].
- * Takes care of tracking requests and responses,
- * serializing data, tracking streams, processing exceptions, and other protocol responsibilities.
- * Leaves out the delivery of encoded messages to the specific implementations.
- *
- * A simple example of how this client may be implemented:
- * ```kotlin
- * class MyTransport : RpcTransport { /*...*/ }
- *
- * class MyClient(config: RpcConfig.Client): KrpcClient(config, MyTransport())
- * ```
+ * Represents an initialized [KrpcClient] that wraps a predefined [config] and [transport] parameters.
  *
  * @param config configuration provided for that specific client. Applied to all services that use this client.
+ * See [KrpcClient.initializeConfig].
  * @param transport [KrpcTransport] instance that will be used to send and receive RPC messages.
- * IMPORTANT: Must be exclusive to this client, otherwise unexpected behavior may occur.
+ * See [KrpcClient.initializeTransport].
+ */
+public abstract class InitializedKrpcClient(
+    private val transport: KrpcTransport,
+    private val config: KrpcConfig.Client,
+): KrpcClient() {
+    final override suspend fun initializeTransport(): KrpcTransport {
+        return transport
+    }
+
+    final override fun initializeConfig(): KrpcConfig.Client {
+        return config
+    }
+}
+
+/**
+ * kRPC implementation of the [RpcClient].
+ * Takes care of tracking requests and responses,
+ * serializing data, tracking streams, processing exceptions, and other protocol responsibilities.
+ * Leaves out the delivery of encoded messages to the specific implementations with [KrpcTransport].
  */
 @OptIn(InternalCoroutinesApi::class)
 public abstract class KrpcClient : RpcClient, KrpcEndpoint {
     /**
-     * Called once to provide [KrpcTransport] for this client
+     * Called once to provide [KrpcTransport] for this client.
+     *
+     * IMPORTANT: The provided instance must be exclusive to this client, otherwise unexpected behavior may occur.
      */
-    public abstract suspend fun initializeTransport(): KrpcTransport
-
-    private var isTransportReady: Boolean = false
-    private var transport: KrpcTransport by Delegates.notNull()
+    protected abstract suspend fun initializeTransport(): KrpcTransport
 
     /**
-     * Called once to provide [KrpcConfig.Client] for this client
+     * Called once to provide [KrpcConfig.Client] for this client.
+     * Called only after [initializeTransport].
+     *
+     * Configuration is applied to all services that use this client.
+     */
+    protected abstract fun initializeConfig(): KrpcConfig.Client
+
+    /*
+     * #####################################################################
+     * #                                                                   #
+     * #                         INTERNALS AHEAD                           #
+     * #                                                                   #
+     * #####################################################################
      */
-    public abstract fun initializeConfig(): KrpcConfig.Client
+
+    private var isTransportReady: Boolean = false
+    private var transport: KrpcTransport by Delegates.notNull()
 
     private val config: KrpcConfig.Client by lazy {
         initializeConfig()
@@ -469,19 +492,3 @@ public abstract class KrpcClient : RpcClient, KrpcEndpoint {
         }
     }
 }
-
-/**
- * Represents an initialized RPC client that wraps a predefined configuration and transport.
- */
-public abstract class InitializedKrpcClient(
-    private val config: KrpcConfig.Client,
-    private val transport: KrpcTransport,
-): KrpcClient() {
-    final override suspend fun initializeTransport(): KrpcTransport {
-        return transport
-    }
-
-    final override fun initializeConfig(): KrpcConfig.Client {
-        return config
-    }
-}