From 735b9ba8063a7881e63b0e7cd21bc3fac88631c5 Mon Sep 17 00:00:00 2001
From: "leonid.stashevsky" <leonid.stashevsky@gmail.com>
Date: Mon, 11 Nov 2024 11:31:42 +0100
Subject: [PATCH] KTOR-6501 Add client KDocs for config and ObservableContent

---
 .../src/io/ktor/client/HttpClientConfig.kt    | 67 +++++++++++++++++--
 .../ktor/client/content/ObservableContent.kt  |  3 +
 .../ktor/client/plugins/DefaultTransform.kt   |  1 -
 3 files changed, 66 insertions(+), 5 deletions(-)

diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClientConfig.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClientConfig.kt
index 52fa222b113..c1ea1122a70 100644
--- a/ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClientConfig.kt
+++ b/ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClientConfig.kt
@@ -7,12 +7,48 @@ package io.ktor.client
 import io.ktor.client.engine.*
 import io.ktor.client.plugins.*
 import io.ktor.util.*
-import io.ktor.util.collections.*
 import io.ktor.utils.io.*
 import kotlin.collections.set
 
 /**
- * A mutable [HttpClient] configuration.
+ * A mutable [HttpClient] configuration used to adjust settings, install plugins and interceptors.
+ *
+ * This class is available as block in [HttpClient] constructor or [HttpClient.config] builder:
+ * ```kotlin
+ * val client = HttpClient { // HttpClientConfig<Engine>()
+ *     // Configure engine settings
+ *     engine { // HttpClientEngineConfig
+ *         threadsCount = 4
+ *         pipelining = true
+ *     }
+ *
+ *     // Install and configure plugins
+ *     install(ContentNegotiation) {
+ *         json()
+ *     }
+ *
+ *     // Configure default request parameters
+ *     defaultRequest {
+ *         url("https://api.example.com")
+ *         header("X-Custom-Header", "value")
+ *     }
+ *
+ *     // Configure client-wide settings
+ *     expectSuccess = true
+ *     followRedirects = true
+ * }
+ * ```
+ * ## Configuring [HttpClientEngine]
+ *
+ * If the engine is specified explicitly, engine specific properties will be available in the engine block:
+ * ```kotlin
+ * val client = HttpClient(CIO) { // HttpClientConfig<CIOEngineConfig>.() -> Unit
+ *     engine { // CIOEngineConfig.() -> Unit
+ *         // engine specific properties
+ *     }
+ * }
+ * ```
+ *
  * Learn more about the client's configuration from
  * [Creating and configuring a client](https://ktor.io/docs/create-client.html).
  */
@@ -25,7 +61,15 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
     internal var engineConfig: T.() -> Unit = {}
 
     /**
-     * Allows you to configure engine parameters.
+     * Builder for configuring engine-specific settings in [HttpClientEngineConfig]
+     * (like dispatcher, threads count, proxy, etc.)
+     *
+     * ```kotlin
+     * val client = HttpClient(CIO) { // HttpClientConfig<CIOEngineConfig>
+     *     engine { // CIOEngineConfig.() -> Unit
+     *         proxy = ProxyBuilder.http("proxy.example.com", 8080)
+     *     }
+     * ```
      *
      * You can learn more from [Engines](https://ktor.io/docs/http-client-engines.html).
      */
@@ -40,11 +84,26 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
     /**
      * Specifies whether the client redirects to URLs provided in the `Location` header.
      * You can disable redirections by setting this property to `false`.
+     *
+     * For the advanced redirection configuration, use [HttpRedirect] plugin.
      */
     public var followRedirects: Boolean = true
 
     /**
-     * Uses [defaultTransformers] to automatically handle simple [ContentType].
+     * Enable body transformations for many common types like [String], [ByteArray], [ByteReadChannel], etc.
+     * These transformations are applied to the request and response bodies.
+     *
+     * The transformers will be used when the response body is received with a type:
+     * ```kotlin
+     * val client = HttpClient()
+     * val bytes = client.get("https://ktor.io")
+     *                   .body<ByteArray>()
+     * ```
+     *
+     * The flag is enabled by default.
+     * You might want to disable it if you want to write your own transformers or handle body manually.
+     *
+     * Check [defaultTransformers] documentation for more details.
      */
     public var useDefaultTransformers: Boolean = true
 
diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/content/ObservableContent.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/content/ObservableContent.kt
index 4a8cc205fdb..12fb1c4dcf9 100644
--- a/ktor-client/ktor-client-core/common/src/io/ktor/client/content/ObservableContent.kt
+++ b/ktor-client/ktor-client-core/common/src/io/ktor/client/content/ObservableContent.kt
@@ -15,6 +15,9 @@ import kotlin.coroutines.*
 
 /**
  * Callback that can be registered to listen for upload/download progress.
+ *
+ * This class is used for callbacks in [HttpRequestBuilder.onDownload] and [HttpRequestBuilder.onUpload].
+ *
  * @param bytesSentTotal number of transmitted bytes.
  * @param contentLength body size. Can be null if the size is unknown.
  */
diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/DefaultTransform.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/DefaultTransform.kt
index 6d35d2a0f6e..29b295283a8 100644
--- a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/DefaultTransform.kt
+++ b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/DefaultTransform.kt
@@ -23,7 +23,6 @@ private val LOGGER = KtorSimpleLogger("io.ktor.client.plugins.defaultTransformer
  * Usually installed by default so there is no need to use it
  * unless you have disabled it via [HttpClientConfig.useDefaultTransformers].
  */
-@OptIn(InternalAPI::class)
 public fun HttpClient.defaultTransformers() {
     requestPipeline.intercept(HttpRequestPipeline.Render) { body ->
         if (context.headers[HttpHeaders.Accept] == null) {