Update documentation

ktorio · Nov 7, 2024 · 2ee64f0 · 2ee64f0
1 parent 983ada2
commit 2ee64f0
Show file tree

Hide file tree

Showing 7 changed files with 108 additions and 61 deletions.
diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/ClientSSESession.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/ClientSSESession.kt
@@ -11,28 +11,38 @@ import kotlinx.coroutines.*
 import kotlinx.coroutines.flow.*
 
 /**
- * A Server-sent events session.
+ * A session for handling Server-Sent Events (SSE) from a server.
  *
  * Example of usage:
  * ```kotlin
- * client.sse("http://localhost:8080/sse") {
+ * client.sse("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
  *         println("Data: ${event.data}")
  *     }
  * }
  * ```
- */
+ *
+ * To learn more, see [the SSE](https://en.wikipedia.org/wiki/Server-sent_events)
+ * and [the SSE specification](https://html.spec.whatwg.org/multipage/server-sent-events.html).
+*/
 public interface SSESession : CoroutineScope {
     /**
-     * An incoming server-sent events flow.
+     * An incoming Server-Sent Events (SSE) flow.
+     *
+     * Each [ServerSentEvent] can contain following fields:
+     * - [ServerSentEvent.data] data field of the event.
+     * - [ServerSentEvent.event] string identifying the type of event.
+     * - [ServerSentEvent.id] event ID.
+     * - [ServerSentEvent.retry] reconnection time, in milliseconds to wait before reconnecting.
+     * - [ServerSentEvent.comments] comment lines starting with a ':' character.
      */
     public val incoming: Flow<ServerSentEvent>
 }
 
 /**
- * A Server-sent events session.
+ * A session with deserialization support for handling Server-Sent Events (SSE) from a server.
  *
  * Example of usage:
  * ```kotlin
@@ -42,7 +52,7 @@ public interface SSESession : CoroutineScope {
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -55,10 +65,21 @@ public interface SSESession : CoroutineScope {
  *     }
  * }
  * ```
+ *
+ * To learn more, see [the SSE](https://en.wikipedia.org/wiki/Server-sent_events)
+ * and [the SSE specification](https://html.spec.whatwg.org/multipage/server-sent-events.html).
  */
 public interface SSESessionWithDeserialization : CoroutineScope {
     /**
-     * An incoming server-sent events flow.
+     * An incoming Server-Sent Events (SSE) flow.
+     *
+     * Each [TypedServerSentEvent] can contain following fields:
+     * - [TypedServerSentEvent.data] data field of the event. It can be deserialized into an object
+     *   of desired type using the [deserialize] function
+     * - [TypedServerSentEvent.event] string identifying the type of event.
+     * - [TypedServerSentEvent.id] event ID.
+     * - [TypedServerSentEvent.retry] reconnection time, in milliseconds to wait before reconnecting.
+     * - [TypedServerSentEvent.comments] comment lines starting with a ':' character.
      */
     public val incoming: Flow<TypedServerSentEvent<String>>
 
@@ -83,7 +104,7 @@ public interface SSESessionWithDeserialization : CoroutineScope {
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -118,7 +139,7 @@ public inline fun <reified T> SSESessionWithDeserialization.deserialize(data: St
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -137,25 +158,28 @@ public inline fun <reified T> SSESessionWithDeserialization.deserialize(
 ): T? = deserialize(event.data)
 
 /**
- * A client Server-sent events session.
+ * A client session for handling Server-Sent Events (SSE) from a server.
  *
  * @property call The HTTP call associated with the session.
  *
  * Example of usage:
  * ```kotlin
- * client.sse("http://localhost:8080/sse") {
+ * client.sse("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
  *         println("Data: ${event.data}")
  *     }
  * }
  * ```
+ *
+ * To learn more, see [the SSE](https://en.wikipedia.org/wiki/Server-sent_events)
+ * and [the SSE specification](https://html.spec.whatwg.org/multipage/server-sent-events.html).
  */
 public class ClientSSESession(public val call: HttpClientCall, delegate: SSESession) : SSESession by delegate
 
 /**
- * A client Server-sent events session with deserialization support.
+ * A client session with deserialization support for handling Server-Sent Events (SSE) from a server.
  *
  * @property call The HTTP call associated with the session.
  *
@@ -167,7 +191,7 @@ public class ClientSSESession(public val call: HttpClientCall, delegate: SSESess
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -180,6 +204,9 @@ public class ClientSSESession(public val call: HttpClientCall, delegate: SSESess
  *     }
  * }
  * ```
+ *
+ * To learn more, see [the SSE](https://en.wikipedia.org/wiki/Server-sent_events)
+ * and [the SSE specification](https://html.spec.whatwg.org/multipage/server-sent-events.html).
  */
 public class ClientSSESessionWithDeserialization(
     public val call: HttpClientCall,

diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/SSE.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/SSE.kt
@@ -23,13 +23,13 @@ import kotlin.coroutines.*
 internal val LOGGER = KtorSimpleLogger("io.ktor.client.plugins.sse.SSE")
 
 /**
- * Indicates if a client engine supports Server-sent events.
+ * Indicates if a client engine supports Server-Sent Events (SSE).
  */
 public data object SSECapability : HttpClientEngineCapability<Unit>
 
 /**
- * Client Server-sent events plugin that allows you to establish an SSE connection to a server
- * and receive Server-sent events from it.
+ * Client Server-Sent Events (SSE) plugin that allows you to establish an SSE connection to a server
+ * and receive Server-Sent Events from it.
  * For a simple session, use [ClientSSESession].
  * For a session with deserialization, use [ClientSSESessionWithDeserialization].
  *
@@ -39,7 +39,7 @@ public data object SSECapability : HttpClientEngineCapability<Unit>
  * }
  *
  * // SSE request
- * client.serverSentEvents("http://localhost:8080/sse") {
+ * client.serverSentEvents("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
@@ -54,7 +54,7 @@ public data object SSECapability : HttpClientEngineCapability<Unit>
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -68,7 +68,8 @@ public data object SSECapability : HttpClientEngineCapability<Unit>
  * }
  * ```
  *
- * To learn more, see [the SSE specification](https://html.spec.whatwg.org/multipage/server-sent-events.html).
+ * To learn more, see [the SSE](https://en.wikipedia.org/wiki/Server-sent_events)
+ * and [the SSE specification](https://html.spec.whatwg.org/multipage/server-sent-events.html).
  */
 @OptIn(InternalAPI::class)
 public val SSE: ClientPlugin<SSEConfig> = createClientPlugin(

diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/builders.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/sse/builders.kt
@@ -139,7 +139,7 @@ public suspend fun HttpClient.serverSentEventsSession(
  *
  * Example of usage:
  * ```kotlin
- * client.serverSentEvents("http://localhost:8080/sse") {
+ * client.serverSentEvents("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
@@ -176,7 +176,7 @@ public suspend fun HttpClient.serverSentEvents(
  *
  * Example of usage:
  * ```kotlin
- * client.serverSentEvents("http://localhost:8080/sse") {
+ * client.serverSentEvents("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
@@ -217,7 +217,7 @@ public suspend fun HttpClient.serverSentEvents(
  *
  * Example of usage:
  * ```kotlin
- * client.serverSentEvents("http://localhost:8080/sse") {
+ * client.serverSentEvents("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
@@ -339,7 +339,7 @@ public suspend fun HttpClient.sseSession(
  *
  * Example of usage:
  * ```kotlin
- * client.sse("http://localhost:8080/sse") {
+ * client.sse("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
@@ -365,7 +365,7 @@ public suspend fun HttpClient.sse(
  *
  * Example of usage:
  * ```kotlin
- * client.sse("http://localhost:8080/sse") {
+ * client.sse("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
@@ -396,7 +396,7 @@ public suspend fun HttpClient.sse(
  *
  * Example of usage:
  * ```kotlin
- * client.sse("http://localhost:8080/sse") {
+ * client.sse("http://localhost:8080/sse") { // `this` is `ClientSSESession`
  *     incoming.collect { event ->
  *         println("Id: ${event.id}")
  *         println("Event: ${event.event}")
@@ -420,7 +420,7 @@ public suspend fun HttpClient.sse(
  * Opens a [ClientSSESessionWithDeserialization] to receive Server-Sent Events (SSE) from a server with ability to
  * deserialize the `data` field of the `TypedServerSentEvent`.
  *
- * @param deserialize The deserializer function to transform the `data` field of the `TypedServerSentEvent` 
+ * @param deserialize The deserializer function to transform the `data` field of the `TypedServerSentEvent`
  *                    into an object
  * @param reconnectionTime The time duration to wait before attempting reconnection in case of connection loss
  * @param showCommentEvents When enabled, events containing only comments field will be presented in the incoming flow
@@ -465,7 +465,7 @@ public suspend fun HttpClient.serverSentEventsSession(
  * Opens a [ClientSSESessionWithDeserialization] to receive Server-Sent Events (SSE) from a server with ability to
  * deserialize the `data` field of the `TypedServerSentEvent`.
  *
- * @param deserialize The deserializer function to transform the `data` field of the `TypedServerSentEvent` 
+ * @param deserialize The deserializer function to transform the `data` field of the `TypedServerSentEvent`
  *                    into an object
  * @param reconnectionTime The time duration to wait before attempting reconnection in case of connection loss
  * @param showCommentEvents When enabled, events containing only comments field will be presented in the incoming flow
@@ -572,7 +572,7 @@ public suspend fun HttpClient.serverSentEventsSession(
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -624,7 +624,7 @@ public suspend fun HttpClient.serverSentEvents(
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -681,7 +681,7 @@ public suspend fun HttpClient.serverSentEvents(
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -872,7 +872,7 @@ public suspend fun HttpClient.sseSession(
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -913,7 +913,7 @@ public suspend fun HttpClient.sse(
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {
@@ -969,7 +969,7 @@ public suspend fun HttpClient.sse(
  *     typeInfo, jsonString ->
  *     val serializer = Json.serializersModule.serializer(typeInfo.kotlinType!!)
  *     Json.decodeFromString(serializer, jsonString)!!
- * }) {
+ * }) { // `this` is `ClientSSESessionWithDeserialization`
  *     incoming.collect { event: TypedServerSentEvent<String> ->
  *         when (event.event) {
  *             "customer" -> {