KTOR-4924 update API docs for the client (#3176)

Author: andreyaksenov

ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClient.kt

@@ -18,19 +18,20 @@ import kotlinx.coroutines.*
 import kotlin.coroutines.*
 
 /**
- * Constructs an asynchronous [HttpClient] using optional [block] for configuring this client.
+ * Creates an asynchronous [HttpClient] with the specified [block] configuration.
  *
- * The [HttpClientEngine] is selected from the dependencies.
- * https://ktor.io/docs/http-client-engines.html
+ * Note that the client requires an engine for processing network requests.
+ * The [HttpClientEngine] is selected from the [dependencies](https://ktor.io/docs/client-dependencies.html).
  */
 @KtorDsl
 public expect fun HttpClient(
     block: HttpClientConfig<*>.() -> Unit = {}
 ): HttpClient
 
 /**
- * Constructs an asynchronous [HttpClient] using the specified [engineFactory]
- * and an optional [block] for configuring this client.
+ * Creates an asynchronous [HttpClient] with the specified [HttpClientEngineFactory] and optional [block] configuration.
+ * Note that a specific platform may require a specific engine for processing requests.
+ * You can learn more about available engines from [Engines](https://ktor.io/docs/http-client-engines.html).
  */
 @KtorDsl
 public fun <T : HttpClientEngineConfig> HttpClient(
@@ -51,8 +52,9 @@ public fun <T : HttpClientEngineConfig> HttpClient(
 }
 
 /**
- * Constructs an asynchronous [HttpClient] using the specified [engine]
- * and a [block] for configuring this client.
+ * Creates an asynchronous [HttpClient] with the specified [HttpClientEngine] and optional [block] configuration.
+ * Note that a specific platform may require a specific engine for processing requests.
+ * You can learn more about available engines from [Engines](https://ktor.io/docs/http-client-engines.html).
  */
 @KtorDsl
 public fun HttpClient(
@@ -61,10 +63,12 @@ public fun HttpClient(
 ): HttpClient = HttpClient(engine, HttpClientConfig<HttpClientEngineConfig>().apply(block), manageEngine = false)
 
 /**
- * Asynchronous client to perform HTTP requests.
+ * A multiplatform asynchronous HTTP client, which allows you to make requests and handle responses,
+ * extend its functionality with plugins, such as authentication, JSON serialization, and so on.
  *
- * This is a generic implementation that uses a specific engine [HttpClientEngine].
- * @property engine: [HttpClientEngine] for executing requests.
+ * You can learn how to create a configure [HttpClient] from
+ * [Creating and configuring a client](https://ktor.io/docs/create-client.html).
+ * @property engine [HttpClientEngine] used to execute network requests.
  */
 @OptIn(InternalAPI::class)
 public class HttpClient(
@@ -88,22 +92,22 @@ public class HttpClient(
     public override val coroutineContext: CoroutineContext = engine.coroutineContext + clientJob
 
     /**
-     * Pipeline used for processing all the requests sent by this client.
+     * A pipeline used for processing all requests sent by this client.
      */
     public val requestPipeline: HttpRequestPipeline = HttpRequestPipeline(userConfig.developmentMode)
 
     /**
-     * Pipeline used for processing all the responses sent by the server.
+     * A pipeline used for processing all responses sent by the server.
      */
     public val responsePipeline: HttpResponsePipeline = HttpResponsePipeline(userConfig.developmentMode)
 
     /**
-     * Pipeline used for sending the request.
+     * A pipeline used for sending a request.
      */
     public val sendPipeline: HttpSendPipeline = HttpSendPipeline(userConfig.developmentMode)
 
     /**
-     * Pipeline used for receiving request.
+     * A pipeline used for receiving a request.
      */
     public val receivePipeline: HttpReceivePipeline = HttpReceivePipeline(userConfig.developmentMode)
 
@@ -113,12 +117,12 @@ public class HttpClient(
     public val attributes: Attributes = Attributes(concurrent = true)
 
     /**
-     * Client engine config.
+     * Provides access to the client's engine configuration.
      */
     public val engineConfig: HttpClientEngineConfig = engine.config
 
     /**
-     * Provides events on client lifecycle
+     * Provides access to the events of the client's lifecycle.
      */
     public val monitor: Events = Events()
 
@@ -188,14 +192,14 @@ public class HttpClient(
     }
 
     /**
-     * Check if the specified [capability] is supported by this client.
+     * Checks if the specified [capability] is supported by this client.
      */
     public fun isSupported(capability: HttpClientEngineCapability<*>): Boolean {
         return engine.supportedCapabilities.contains(capability)
     }
 
     /**
-     * Returns a new [HttpClient] copying this client configuration,
+     * Returns a new [HttpClient] by copying this client's configuration
      * and additionally configured by the [block] parameter.
      */
     public fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient = HttpClient(

ktor-client/ktor-client-core/common/src/io/ktor/client/HttpClientConfig.kt

@@ -12,7 +12,9 @@ import io.ktor.utils.io.concurrent.*
 import kotlin.collections.set
 
 /**
- * Mutable configuration used by [HttpClient].
+ * A mutable [HttpClient] configuration.
+ * Learn more about the client's configuration from
+ * [Creating and configuring a client](https://ktor.io/docs/create-client.html).
  */
 @KtorDsl
 public class HttpClientConfig<T : HttpClientEngineConfig> {
@@ -23,7 +25,9 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
     internal var engineConfig: T.() -> Unit = {}
 
     /**
-     * Configure engine parameters.
+     * Allows you to configure engine parameters.
+     *
+     * You can learn more from [Engines](https://ktor.io/docs/http-client-engines.html).
      */
     public fun engine(block: T.() -> Unit) {
         val oldConfig = engineConfig
@@ -34,27 +38,31 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
     }
 
     /**
-     * Use [HttpRedirect] plugin to automatically follow redirects.
+     * Specifies whether the client redirects to URLs provided in the `Location` header.
+     * You can disable redirections by setting this property to `false`.
      */
     public var followRedirects: Boolean = true
 
     /**
-     * Use [defaultTransformers] to automatically handle simple [ContentType].
+     * Uses [defaultTransformers] to automatically handle simple [ContentType].
      */
     public var useDefaultTransformers: Boolean = true
 
     /**
-     * Terminate [HttpClient.receivePipeline] if status code is not successful (>=300).
+     * Terminates [HttpClient.receivePipeline] if the status code is not successful (>=300).
+     * Learn more from [Response validation](https://ktor.io/docs/response-validation.html).
      */
     public var expectSuccess: Boolean = false
 
     /**
-     * Indicate if client should use development mode. In development mode client pipelines have advanced stack traces.
+     * Indicates whether the client should use [development mode](https://ktor.io/docs/development-mode.html).
+     * In development mode, the client's pipelines have advanced stack traces.
      */
     public var developmentMode: Boolean = PlatformUtils.IS_DEVELOPMENT_MODE
 
     /**
-     * Installs a specific [plugin] and optionally [configure] it.
+     * Installs the specified [plugin] and optionally configures it using the [configure] block.
+     * Learn more from [Plugins](https://ktor.io/docs/http-client-plugins.html).
      */
     public fun <TBuilder : Any, TPlugin : Any> install(
         plugin: HttpClientPlugin<TBuilder, TPlugin>,
@@ -98,7 +106,7 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
     }
 
     /**
-     * Clones this [HttpClientConfig] duplicating all the [plugins] and [customInterceptors].
+     * Clones this [HttpClientConfig] by duplicating all the [plugins] and [customInterceptors].
      */
     public fun clone(): HttpClientConfig<T> {
         val result = HttpClientConfig<T>()
@@ -107,7 +115,7 @@ public class HttpClientConfig<T : HttpClientEngineConfig> {
     }
 
     /**
-     * Install plugin from [other] client config.
+     * Installs the plugin from the [other] client's configuration.
      */
     public operator fun plusAssign(other: HttpClientConfig<out T>) {
         followRedirects = other.followRedirects

ktor-client/ktor-client-core/common/src/io/ktor/client/call/HttpClientCall.kt

@@ -18,9 +18,9 @@ import kotlin.coroutines.*
 import kotlin.reflect.*
 
 /**
- * A class that represents a single pair of [request] and [response] for a specific [HttpClient].
+ * A pair of a [request] and [response] for a specific [HttpClient].
  *
- * @property client: client that executed the call.
+ * @property client the client that executed the call.
  */
 public open class HttpClientCall(
     public val client: HttpClient
@@ -35,13 +35,13 @@ public open class HttpClientCall(
     public val attributes: Attributes get() = request.attributes
 
     /**
-     * Represents the [request] sent by the client
+     * The [request] sent by the client.
      */
     public lateinit var request: HttpRequest
         protected set
 
     /**
-     * Represents the [response] sent by the server.
+     * The [response] sent by the server.
      */
     public lateinit var response: HttpResponse
         protected set

ktor-client/ktor-client-core/common/src/io/ktor/client/engine/HttpClientEngine.kt

@@ -19,16 +19,16 @@ internal val CALL_COROUTINE = CoroutineName("call-context")
 internal val CLIENT_CONFIG = AttributeKey<HttpClientConfig<*>>("client-config")
 
 /**
- * Base interface use to define engines for [HttpClient].
+ * Serves as the base interface for an [HttpClient]'s engine.
  */
 public interface HttpClientEngine : CoroutineScope, Closeable {
     /**
-     * [CoroutineDispatcher] specified for io operations.
+     * Specifies [CoroutineDispatcher] for I/O operations.
      */
     public val dispatcher: CoroutineDispatcher
 
     /**
-     * Engine configuration
+     * Provides access to an engine's configuration.
      */
     public val config: HttpClientEngineConfig
 
@@ -48,7 +48,7 @@ public interface HttpClientEngine : CoroutineScope, Closeable {
     public suspend fun execute(data: HttpRequestData): HttpResponseData
 
     /**
-     * Install engine into [HttpClient].
+     * Installs the engine to [HttpClient].
      */
     @InternalAPI
     public fun install(client: HttpClient) {
@@ -84,7 +84,7 @@ public interface HttpClientEngine : CoroutineScope, Closeable {
     }
 
     /**
-     * Create call context and use it as a coroutine context to [execute] request.
+     * Creates a call context and uses it as a coroutine context to [execute] a request.
      */
     @OptIn(InternalAPI::class)
     private suspend fun executeWithinCallContext(requestData: HttpRequestData): HttpResponseData {
@@ -108,7 +108,7 @@ public interface HttpClientEngine : CoroutineScope, Closeable {
 }
 
 /**
- * Factory of [HttpClientEngine] with a specific [T] of [HttpClientEngineConfig].
+ * A factory of [HttpClientEngine] with a specific [T] of [HttpClientEngineConfig].
  */
 public interface HttpClientEngineFactory<out T : HttpClientEngineConfig> {
     /**
@@ -135,7 +135,7 @@ public fun <T : HttpClientEngineConfig> HttpClientEngineFactory<T>.config(
 }
 
 /**
- * Create call context with the specified [parentJob] to be used during call execution in the engine. Call context
+ * Creates a call context with the specified [parentJob] to be used during call execution in the engine. Call context
  * inherits [coroutineContext], but overrides job and coroutine name so that call job's parent is [parentJob] and
  * call coroutine's name is "call-context".
  */

ktor-client/ktor-client-core/common/src/io/ktor/client/engine/HttpClientEngineBase.kt

@@ -35,13 +35,13 @@ public abstract class HttpClientEngineBase(private val engineName: String) : Htt
 }
 
 /**
- * Exception that indicates that client engine is already closed.
+ * An exception indicating that the client's engine is already closed.
  */
 public class ClientEngineClosedException(override val cause: Throwable? = null) :
     IllegalStateException("Client already closed")
 
 /**
- * Close [CoroutineDispatcher] if it's [CloseableCoroutineDispatcher] or [Closeable].
+ * Closes [CoroutineDispatcher] if it's [CloseableCoroutineDispatcher] or [Closeable].
  */
 @OptIn(ExperimentalCoroutinesApi::class)
 private fun CoroutineDispatcher.close() {

ktor-client/ktor-client-core/common/src/io/ktor/client/request/HttpRequest.kt

@@ -53,7 +53,9 @@ public interface HttpRequest : HttpMessage, CoroutineScope {
 }
 
 /**
- * Class for building [HttpRequestData].
+ * Contains parameters used to make an HTTP request.
+ *
+ * Learn more from [Making requests](https://ktor.io/docs/request.html).
  */
 @Suppress("DEPRECATION")
 public class HttpRequestBuilder : HttpMessageBuilder {
@@ -98,7 +100,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
         internal set
 
     /**
-     * Call specific attributes.
+     * Provides access to attributes specific for this request.
      */
     public val attributes: Attributes = Attributes(concurrent = true)
 
@@ -108,7 +110,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
     public fun url(block: URLBuilder.(URLBuilder) -> Unit): Unit = url.block(url)
 
     /**
-     * Create immutable [HttpRequestData]
+     * Creates immutable [HttpRequestData].
      */
     @OptIn(InternalAPI::class)
     public fun build(): HttpRequestData = HttpRequestData(
@@ -121,14 +123,14 @@ public class HttpRequestBuilder : HttpMessageBuilder {
     )
 
     /**
-     * Set request specific attributes specified by [block].
+     * Sets request-specific attributes specified by [block].
      */
     public fun setAttributes(block: Attributes.() -> Unit) {
         attributes.apply(block)
     }
 
     /**
-     * Mutates [this] copying all the data from another [builder] using it as base.
+     * Mutates [this] copying all the data from another [builder] using it as the base.
      */
     @InternalAPI
     public fun takeFromWithExecutionContext(builder: HttpRequestBuilder): HttpRequestBuilder {
@@ -137,7 +139,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
     }
 
     /**
-     * Mutates [this] copying all the data but execution context from another [builder] using it as base.
+     * Mutates [this] by copying all the data but execution context from another [builder] using it as the base.
      */
     @OptIn(InternalAPI::class)
     public fun takeFrom(builder: HttpRequestBuilder): HttpRequestBuilder {
@@ -153,7 +155,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
     }
 
     /**
-     * Set capability configuration.
+     * Sets capability configuration.
      */
     @OptIn(InternalAPI::class)
     public fun <T : Any> setCapability(key: HttpClientEngineCapability<T>, capability: T) {
@@ -162,7 +164,7 @@ public class HttpRequestBuilder : HttpMessageBuilder {
     }
 
     /**
-     * Retrieve capability by key.
+     * Retrieves capability by the key.
      */
     public fun <T : Any> getCapabilityOrNull(key: HttpClientEngineCapability<T>): T? {
         @Suppress("UNCHECKED_CAST")
@@ -257,14 +259,14 @@ public fun HttpRequestBuilder.takeFrom(request: HttpRequestData): HttpRequestBui
 }
 
 /**
- * Executes a [block] that configures the [URLBuilder] associated to thisrequest.
+ * Executes a [block] that configures the [URLBuilder] associated to this request.
  */
 public operator fun HttpRequestBuilder.Companion.invoke(block: URLBuilder.() -> Unit): HttpRequestBuilder =
     HttpRequestBuilder().apply { url(block) }
 
 /**
  * Sets the [url] using the specified [scheme], [host], [port] and [path].
- * Pass `null` to keep existing value in the [URLBuilder].
+ * Pass `null` to keep the existing value in the [URLBuilder].
  */
 public fun HttpRequestBuilder.url(
     scheme: String? = null,
@@ -279,7 +281,7 @@ public fun HttpRequestBuilder.url(
 /**
  * Constructs a [HttpRequestBuilder] from URL information: [scheme], [host], [port] and [path]
  * and optionally further configures it using [block].
- * Pass `null` to keep existing value in the [URLBuilder].
+ * Pass `null` to keep the existing value in the [URLBuilder].
  */
 public operator fun HttpRequestBuilder.Companion.invoke(
     scheme: String? = null,