Review comments

Mr3zee · Mr3zee · commit 12ff49457bb9 · 2025-01-24T11:58:14.000+01:00
diff --git a/docs/pages/kotlinx-rpc/topics/0-5-0.topic b/docs/pages/kotlinx-rpc/topics/0-5-0.topic
@@ -11,8 +11,8 @@
 
     <chapter title="Annotation type-safety" id="annotation-type-safety">
         <p>
-            This release brings <a href="annotation-type-safety.topic">annotation type-safety</a>.
-            This means that some green code technically can become red:
+            This release introduces <a href="annotation-type-safety.topic">annotation type-safety</a>.
+            As a result, some code that previously compiled successfully may now produce errors:
         </p>
         <code-block lang="Kotlin">
             @Rpc
@@ -28,15 +28,16 @@
             withService&lt;MyServiceImpl&gt;() // ok in 0.4.0, error in 0.5.0
         </code-block>
         <p>
-            Thar should not be a problem, as this code was wrong in both releases anyway and would fail in runtime in <code>0.4.0</code>.
+            This should not cause any major issues, as the affected code was already incorrect
+            in previous releases and would have failed at runtime in <code>0.4.0</code>.
         </p>
     </chapter>
 
     <chapter title="Strict Mode and Service API deprecations" id="strict-mode">
         <p>
             This release introduces <a href="strict-mode.topic">Strict Mode</a>.
-            Some service declarations are now deprecated, currently with a warning.
-            In the following releases it will change to an error.
+            Some service declarations are now deprecated with a warning.
+            In upcoming releases, these warnings will be replaced with errors.
         </p>
         <p>
             Deprecated service APIs:
@@ -48,7 +49,7 @@
             <li>Not top-level server side flows</li>
         </list>
         <p>
-            More info on the <a href="strict-mode.topic">Strict Mode page</a>.
+            For more information, see the <a href="strict-mode.topic">Strict Mode</a> documentation.
         </p>
     </chapter>
 
diff --git a/docs/pages/kotlinx-rpc/topics/annotation-type-safety.topic b/docs/pages/kotlinx-rpc/topics/annotation-type-safety.topic
@@ -6,7 +6,7 @@
        title="Annotation type-safety" id="annotation-type-safety">
 
     <p>
-        Library introduces a concept of annotation type-safety. Consider the following example:
+        The library introduces a concept of annotation type-safety. Consider the following example:
     </p>
     <code-block lang="Kotlin">
         @Rpc
@@ -17,14 +17,15 @@
         fun &lt;T : RemoteService&gt; withService() {}
     </code-block>
     <p>
-        Compiler can not guarantee, that the passed type is the one for which the code generation was run:
+        The compiler can't guarantee that the passed type parameter is the one for which the code generation was run:
     </p>
     <code-block lang="Kotlin">
         withService&lt;MyService&gt;() // ok
         withService&lt;MyServiceImpl&gt;() // compile time ok, runtime throws
     </code-block>
     <p>
-        Our compiler plugin, however, can make this code behave as expected.
+        The compiler plugin enforces annotation type-safety by requiring type parameters to have specific annotations,
+        like <code>@Rpc</code>.
     </p>
     <code-block lang="Kotlin">
         @Rpc
@@ -41,27 +42,27 @@
     </code-block>
 
     <note>
-        Annotation type safety only ensures that the resolved type parameters are annotated with the required annotation.
+        Annotation type safety only ensures that the resolved type parameters are annotated with the required
+        annotation.
         The actual type of the passed argument may differ:
         <code-block lang="Kotlin">
             fun &lt;@Rpc T : Any&gt; registerService(body: () -> T) {}
 
-            // ok, T is resolved to MyService,
-            // but 'body' parameter returns MyServiceImpl
+            // T is resolved to MyService,
+            // but 'body' returns MyServiceImpl
             registerService&lt;MyService&gt; { ctx -> MyServiceImpl(ctx) }
 
-            // error, T is resolved to MyServiceImpl
+            // Error: T is resolved to MyServiceImpl
             registerService { ctx -> MyServiceImpl(ctx) }
         </code-block>
     </note>
 
     <warning>
-        The feature is highly experimental.
-        The concept will stay, however due to the complexity of the implementation,
-        our compiler plugin may behave unexpectedly when performing type-safety checks.
-        Please, <a href="https://github.com/Kotlin/kotlinx-rpc/issues/new?template=bug_report.md">report</a> any encountered bugs.
+        This feature is highly experimental and may lead to unexpected behaviour. If you encounter any issues,
+        please <a href="https://github.com/Kotlin/kotlinx-rpc/issues/new?template=bug_report.md">report</a> them.
 
-        To ensure critical bugs don't paralyze your app, there is a kill-switch present for the feature:
+        To prevent critical bugs from affecting your app, you can disable this feature using the following
+        configuration:
         <code-block lang="Kotlin">
             // build.gradle.kts
             rpc {
diff --git a/docs/pages/kotlinx-rpc/topics/configuration.topic b/docs/pages/kotlinx-rpc/topics/configuration.topic
@@ -54,7 +54,8 @@
             </title>
 
             <warning>
-                These parameters are deprecated since <code>0.5.0</code>, see the <a href="0-5-0.topic">migration guide</a>.
+                These parameters are deprecated since <code>0.5.0</code>. For more information,
+                see the <a href="0-5-0.topic">migration guide</a>.
             </warning>
 
             <code-block lang="kotlin">
diff --git a/docs/pages/kotlinx-rpc/topics/features.topic b/docs/pages/kotlinx-rpc/topics/features.topic
@@ -12,8 +12,8 @@
         <p>
             You can send and receive <a href="https://kotlinlang.org/docs/flow.html">Kotlin Flows</a> in RPC
             methods.
-            This is only applied to <code>Flow</code> type, <code>StateFlow</code> and <code>SharedFlow</code>
-            are not supported and there are no plans to do so.
+            However, this only applies to the <code>Flow</code> type. <code>StateFlow</code> and <code>SharedFlow</code>
+            are not supported, and there are no plans to add support for them.
         </p>
 
         <code-block lang="kotlin">
@@ -32,7 +32,7 @@
         </code-block>
 
         <p>
-            Another limitation is that server-side steaming (flows that are returned from a function),
+            Another requirement is that server-side steaming (flows that are returned from a function),
             must be the top-level type:
         </p>
 
@@ -51,13 +51,13 @@
         </code-block>
 
         <note>
-            Note that flows that are declared in classes (like in <code>StreamResult</code>) require
+            Note that flows that are declared in classes (like in <code>StreamResult</code>) require a
             <a href="https://github.com/Kotlin/kotlinx.serialization/blob/master/docs/serializers.md#contextual-serialization">Contextual</a>
             annotation.
         </note>
 
         <p>
-            To use flows in your code - you need to use special <code>streamScoped</code> function
+            To use flows in your code, use the <code>streamScoped</code> function
             that will provide your flows with their lifetime:
         </p>
 
@@ -85,17 +85,17 @@
             After that, all streams that are still live will be closed.
         </p>
         <p>
-            You can have multiple RPC call and flows inside the <code>streamScoped</code> function, even from
+            You can have multiple RPC calls and flows inside the <code>streamScoped</code> function, including those from
             different services.
         </p>
         <p>
-            On server side, you can use <code>invokeOnStreamScopeCompletion</code> handler inside your methods
-            to execute code after <code>streamScoped</code> on client side has closed.
+            On the server side, you can use the <code>invokeOnStreamScopeCompletion</code> handler inside your methods
+            to execute code after <code>streamScoped</code> on the client side has closed.
             It might be useful to clean resources, for example.
         </p>
-        <note>
+        <warning>
             Note that this API is experimental and may be removed in future releases.
-        </note>
+        </warning>
         <p>
             Another way of managing streams is to do it manually.
             For this, you can use the <code>StreamScope</code> constructor function together with
diff --git a/docs/pages/kotlinx-rpc/topics/service-descriptors.topic b/docs/pages/kotlinx-rpc/topics/service-descriptors.topic
@@ -9,13 +9,13 @@
         This API is experimental and may be changed at any time.
     </note>
     <p>
-        Service Descriptors allow to access entities generated by the compiler plugin.
-        API can be accessed using the following code:
+        Service Descriptors allow you to access entities generated by the compiler plugin.
+        You can access them by using the following code:
     </p>
     <code-block lang="Kotlin">
         serviceDescriptorOf&lt;MyService&gt;()
     </code-block>
     <p>
-        The list of available entities can be found <a href="https://github.com/Kotlin/kotlinx-rpc/blob/main/core/src/commonMain/kotlin/kotlinx/rpc/descriptor/RpcServiceDescriptor.kt">in code</a>
+        For the list of available entities, refer to <a href="https://github.com/Kotlin/kotlinx-rpc/blob/main/core/src/commonMain/kotlin/kotlinx/rpc/descriptor/RpcServiceDescriptor.kt">the source code</a>.
     </p>
 </topic>
diff --git a/docs/pages/kotlinx-rpc/topics/strict-mode.topic b/docs/pages/kotlinx-rpc/topics/strict-mode.topic
@@ -6,12 +6,12 @@
        title="Strict mode" id="strict-mode">
 
     <p>
-        Starting with version <code>0.5.0</code> library undergoes major change in supported service APIs.
+        Starting with version <code>0.5.0</code>, the library introduces major changes to the service APIs.
         The following declarations will be gradually restricted:
     </p>
     <list>
         <li>
-            <b>StateFlow and SharedFlow</b>
+            <b><code>StateFlow</code> and <code>SharedFlow</code></b>
             <p>Deprecation level: <code>WARNING</code></p>
             <code-block lang="kotlin">
                 @Rpc
@@ -66,7 +66,7 @@
     </list>
 
     <p>
-        Deprecation levels are controlled by the Gradle `rpc` extension:
+        Deprecation levels are controlled by the Gradle <code>rpc</code> extension:
     </p>
     <code-block lang="Kotlin">
         // build.gradle.kts
@@ -88,9 +88,9 @@
         Modes <code>RpcStrictMode.NONE</code> and <code>RpcStrictMode.ERROR</code> are available.
     </p>
 
-    <note>
+    <warning>
         Note that setting <code>RpcStrictMode.NONE</code> should not be done permanently.
         All deprecated APIs will become errors in future without an option to suppress it.
         Consider your migration path in advance.
-    </note>
+    </warning>
 </topic>
