Documentation update for 0.8.0 (#351)

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)

docs/pages/kotlinx-rpc/rpc.tree

@@ -24,7 +24,11 @@
         <toc-element toc-title="kRPC">
             <toc-element topic="configuration.topic"/>
             <toc-element topic="features.topic"/>
-            <toc-element topic="transport.topic"/>
+            <toc-element topic="krpc-client.topic"/>
+            <toc-element topic="krpc-server.topic"/>
+            <toc-element topic="transport.topic">
+                <toc-element topic="krpc-ktor.topic"/>
+            </toc-element>
         </toc-element>
         <toc-element toc-title="gRPC">
             <toc-element topic="grpc-configuration.topic"/>
@@ -36,6 +40,7 @@
     <toc-element topic="strict-mode.topic"/>
     <toc-element topic="versions.topic"/>
     <toc-element toc-title="Migration guides">
+        <toc-element topic="0-8-0.topic"/>
         <toc-element topic="0-6-0.topic"/>
         <toc-element topic="0-5-0.topic"/>
         <toc-element topic="0-4-0.topic"/>