diff --git a/ktor-client/ktor-client-android/jvm/src/io/ktor/client/engine/android/AndroidURLConnectionUtils.kt b/ktor-client/ktor-client-android/jvm/src/io/ktor/client/engine/android/AndroidURLConnectionUtils.kt index 7c83aee467d..0b912886f2c 100644 --- a/ktor-client/ktor-client-android/jvm/src/io/ktor/client/engine/android/AndroidURLConnectionUtils.kt +++ b/ktor-client/ktor-client-android/jvm/src/io/ktor/client/engine/android/AndroidURLConnectionUtils.kt @@ -18,7 +18,7 @@ import java.net.* import kotlin.coroutines.* /** - * Setup [HttpURLConnection] timeout configuration using [HttpTimeout.HttpTimeoutCapabilityConfiguration] as a source. + * Setup [HttpURLConnection] timeout configuration using [HttpTimeoutConfig] as a source. */ @OptIn(InternalAPI::class) internal fun HttpURLConnection.setupTimeoutAttributes(requestData: HttpRequestData) { diff --git a/ktor-client/ktor-client-apache5/jvm/src/io/ktor/client/engine/apache5/Apache5.kt b/ktor-client/ktor-client-apache5/jvm/src/io/ktor/client/engine/apache5/Apache5.kt index dff6e8230b5..182bd4eb058 100644 --- a/ktor-client/ktor-client-apache5/jvm/src/io/ktor/client/engine/apache5/Apache5.kt +++ b/ktor-client/ktor-client-apache5/jvm/src/io/ktor/client/engine/apache5/Apache5.kt @@ -14,7 +14,7 @@ import io.ktor.client.engine.* * ```kotlin * val client = HttpClient(Apache) * ``` - * To configure the engine, pass settings exposed by [ApacheEngineConfig] to the `engine` method: + * To configure the engine, pass settings exposed by [Apache5EngineConfig] to the `engine` method: * ```kotlin * val client = HttpClient(Apache) { * engine { diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/cache/storage/HttpCacheStorage.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/cache/storage/HttpCacheStorage.kt index c30d2108fda..60cdc328098 100644 --- a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/cache/storage/HttpCacheStorage.kt +++ b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/cache/storage/HttpCacheStorage.kt @@ -12,11 +12,9 @@ import io.ktor.client.plugins.cache.* import io.ktor.client.request.* import io.ktor.client.statement.* import io.ktor.http.* -import io.ktor.util.* import io.ktor.util.date.* import io.ktor.utils.io.* import io.ktor.utils.io.core.* -import kotlinx.coroutines.* import kotlin.coroutines.* /** @@ -67,7 +65,7 @@ internal suspend fun HttpCacheStorage.store(url: Url, value: HttpResponse, isSha public interface CacheStorage { /** - * Store [value] in cache storage for [url] key. + * Store [data] in cache storage for [url] key. */ public suspend fun store(url: Url, data: CachedResponseData) diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/websocket/ClientSessions.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/websocket/ClientSessions.kt index 2c53e461f79..f2a9b5adee2 100644 --- a/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/websocket/ClientSessions.kt +++ b/ktor-client/ktor-client-core/common/src/io/ktor/client/plugins/websocket/ClientSessions.kt @@ -49,9 +49,8 @@ public val DefaultClientWebSocketSession.converter: WebsocketContentConverter? * Frames sent after a Close frame are silently ignored. * Note that a Close frame could be sent automatically in reply to a peer's Close frame unless it is a raw WebSocket session. * - * @param typeInfo Type info of [T]. Can be retrieved with [typeInfo] function. - * - * @throws WebsocketConverterNotFoundException if no [contentConverter] is found for the [WebSockets] plugin + * @type the type of the data to be serialized + * @throws WebsocketConverterNotFoundException if no [DefaultClientWebSocketSession.converter] is found for the [WebSockets] plugin */ @OptIn(InternalAPI::class) public suspend fun DefaultClientWebSocketSession.sendSerialized(data: Any?, typeInfo: TypeInfo) { @@ -73,7 +72,7 @@ public suspend fun DefaultClientWebSocketSession.sendSerialized(data: Any?, type * Frames sent after a Close frame are silently ignored. * Note that a Close frame could be sent automatically in reply to a peer's Close frame unless it is a raw WebSocket session. * - * @throws WebsocketConverterNotFoundException if no [contentConverter] is found for the [WebSockets] plugin + * @throws WebsocketConverterNotFoundException if no [DefaultClientWebSocketSession.converter] is found for the [WebSockets] plugin */ public suspend inline fun DefaultClientWebSocketSession.sendSerialized(data: T) { sendSerialized(data, typeInfo()) @@ -111,7 +110,7 @@ public suspend fun DefaultClientWebSocketSession.receiveDeserialized(typeInf * In this case, [WebsocketDeserializeException.frame] contains the received frame. * May throw [ClosedReceiveChannelException] if a channel was closed * - * @throws WebsocketConverterNotFoundException if no [contentConverter] is found for the [WebSockets] plugin + * @throws WebsocketConverterNotFoundException if no [DefaultClientWebSocketSession.converter] is found for the [WebSockets] plugin * @throws WebsocketDeserializeException if the received frame can't be deserialized to type [T] */ public suspend inline fun DefaultClientWebSocketSession.receiveDeserialized(): T = diff --git a/ktor-client/ktor-client-core/common/src/io/ktor/client/utils/CIO.kt b/ktor-client/ktor-client-core/common/src/io/ktor/client/utils/CIO.kt index f71de6da207..26bb08de249 100644 --- a/ktor-client/ktor-client-core/common/src/io/ktor/client/utils/CIO.kt +++ b/ktor-client/ktor-client-core/common/src/io/ktor/client/utils/CIO.kt @@ -5,11 +5,20 @@ package io.ktor.client.utils /** - * Maximum number of buffers to be allocated in the [HttpClientDefaultPool]. + * This constant is not used anymore and will be removed in the future releases. */ +@Deprecated( + "This constant is not used anymore and will be removed in the future releases.", + level = DeprecationLevel.WARNING +) + public const val DEFAULT_HTTP_POOL_SIZE: Int = 1000 /** - * Size of each buffer in the [HttpClientDefaultPool]. + * This constant is not used anymore and will be removed in the future releases. */ +@Deprecated( + "This constant is not used anymore and will be removed in the future releases.", + level = DeprecationLevel.WARNING +) public const val DEFAULT_HTTP_BUFFER_SIZE: Int = 4096 diff --git a/ktor-client/ktor-client-core/jvm/src/io/ktor/client/request/buildersJvm.kt b/ktor-client/ktor-client-core/jvm/src/io/ktor/client/request/buildersJvm.kt index a253dc225d7..ac38b864a0a 100644 --- a/ktor-client/ktor-client-core/jvm/src/io/ktor/client/request/buildersJvm.kt +++ b/ktor-client/ktor-client-core/jvm/src/io/ktor/client/request/buildersJvm.kt @@ -26,7 +26,7 @@ public suspend fun HttpClient.request( * Executes a [HttpClient] GET request, with the specified [url] as URL and * an optional [block] receiving an [HttpRequestBuilder] for further configuring the request. * - * Tries to receive a specific type [T], if fails, an exception is thrown. + * Tries to receive a [HttpResponse], if fails, an exception is thrown. */ public suspend fun HttpClient.get( url: URL, @@ -123,8 +123,6 @@ public suspend fun HttpClient.prepareRequest( /** * Prepares a [HttpClient] GET request, with the specified [url] as URL and * an optional [block] receiving an [HttpRequestBuilder] for further configuring the request. - * - * Tries to receive a specific type [T], if fails, an exception is thrown. */ public suspend fun HttpClient.prepareGet( url: URL, diff --git a/ktor-client/ktor-client-core/jvm/src/io/ktor/client/utils/CIOJvm.kt b/ktor-client/ktor-client-core/jvm/src/io/ktor/client/utils/CIOJvm.kt index 2b55fe619a3..5f15c8f8fa7 100644 --- a/ktor-client/ktor-client-core/jvm/src/io/ktor/client/utils/CIOJvm.kt +++ b/ktor-client/ktor-client-core/jvm/src/io/ktor/client/utils/CIOJvm.kt @@ -10,6 +10,6 @@ import io.ktor.utils.io.pool.* import java.nio.* /** - * Singleton pool of [ByteBuffer] objects used for [HttpClient]. + * Singleton pool of [ByteBuffer] objects used for [io.ktor.client.HttpClient]. */ public val HttpClientDefaultPool: ByteBufferPool = ByteBufferPool() diff --git a/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/Auth.kt b/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/Auth.kt index 1fd57fa6d25..543edc7cb1d 100644 --- a/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/Auth.kt +++ b/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/Auth.kt @@ -39,7 +39,7 @@ public val AuthCircuitBreaker: AttributeKey = AttributeKey("auth-request") * * You can learn more from [Authentication and authorization](https://ktor.io/docs/auth.html). * - * [providers] - list of auth providers to use. + * [AuthConfig.providers] - List of auth providers to use. */ public val Auth: ClientPlugin = createClientPlugin("Auth", ::AuthConfig) { val providers = pluginConfig.providers.toList() diff --git a/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/AuthProvider.kt b/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/AuthProvider.kt index 3dda8f14bf2..b469ee2013e 100644 --- a/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/AuthProvider.kt +++ b/ktor-client/ktor-client-plugins/ktor-client-auth/common/src/io/ktor/client/plugins/auth/AuthProvider.kt @@ -38,7 +38,7 @@ public interface AuthProvider { /** * Refreshes a token if required. * - * @param call - response triggered token refresh. + * @param response - response triggered token refresh. * @return if the token was successfully refreshed. */ public suspend fun refreshToken(response: HttpResponse): Boolean = true diff --git a/ktor-io/common/src/io/ktor/utils/io/ByteReadChannelOperations.kt b/ktor-io/common/src/io/ktor/utils/io/ByteReadChannelOperations.kt index eee738d5b1b..46a26978c0f 100644 --- a/ktor-io/common/src/io/ktor/utils/io/ByteReadChannelOperations.kt +++ b/ktor-io/common/src/io/ktor/utils/io/ByteReadChannelOperations.kt @@ -14,7 +14,6 @@ import kotlinx.io.Buffer import kotlinx.io.bytestring.* import kotlinx.io.unsafe.* import kotlin.coroutines.* -import kotlin.jvm.* import kotlin.math.* @OptIn(InternalAPI::class) @@ -133,7 +132,7 @@ public suspend fun ByteReadChannel.copyAndClose(channel: ByteWriteChannel): Long * It recognizes CR, LF and CRLF as line delimiters. * * @param max the maximum number of characters to read. Default is [Int.MAX_VALUE]. - * @return a string containing the line read, or null if channel is closed + * @return a string containing the line read, or null if the channel is closed * @throws TooLongLineException if max is reached before encountering a newline or end of input */ public suspend fun ByteReadChannel.readUTF8Line(max: Int = Int.MAX_VALUE): String? { @@ -223,7 +222,7 @@ public suspend fun ByteReadChannel.readRemaining(max: Long): Source { } /** - * Reads all available bytes to [dst] buffer and returns immediately or suspends if no bytes available + * Reads all available bytes to [buffer] buffer and returns immediately or suspends if no bytes available * @return number of bytes were read or `-1` if the channel has been closed */ @OptIn(InternalAPI::class) @@ -242,9 +241,9 @@ public suspend fun ByteReadChannel.readAvailable( /** * Invokes [block] if it is possible to read at least [min] byte * providing buffer to it so lambda can read from the buffer - * up to [Buffer.readRemaining] bytes. If there are no [min] bytes available then the invocation returns -1. + * up to [Buffer.size] bytes. If there are no [min] bytes available then the invocation returns -1. * - * Warning: it is not guaranteed that all of available bytes will be represented as a single byte buffer + * Warning: it is not guaranteed that all available bytes will be represented as a single byte buffer * eg: it could be 4 bytes available for read but the provided byte buffer could have only 2 available bytes: * in this case you have to invoke read again (with decreased [min] accordingly). * diff --git a/ktor-io/jvm/src/io/ktor/utils/io/ByteReadChannelOperations.jvm.kt b/ktor-io/jvm/src/io/ktor/utils/io/ByteReadChannelOperations.jvm.kt index 11b9dce6262..9a244abea74 100644 --- a/ktor-io/jvm/src/io/ktor/utils/io/ByteReadChannelOperations.jvm.kt +++ b/ktor-io/jvm/src/io/ktor/utils/io/ByteReadChannelOperations.jvm.kt @@ -49,7 +49,7 @@ public fun ByteString(buffer: ByteBuffer): ByteString { /** * Copy up to [limit] bytes to blocking NIO [channel]. * Copying to a non-blocking channel requires selection and not supported. - * It is suspended if no data are available in a byte channel but may block if destination NIO channel blocks. + * It is suspended if no data is available in a byte channel but may block if destination NIO channel blocks. * * @return number of bytes copied */ @@ -124,10 +124,11 @@ public suspend fun ByteReadChannel.readFully(buffer: ByteBuffer) { /** * Invokes [block] if it is possible to read at least [min] byte * providing byte buffer to it so lambda can read from the buffer - * up to [ByteBuffer.available] bytes. If there are no [min] bytes available then the invocation returns 0. + * up to [ByteBuffer.remaining] bytes. + * If there are no [min] bytes available then the invocation returns 0. * - * Warning: it is not guaranteed that all of available bytes will be represented as a single byte buffer - * eg: it could be 4 bytes available for read but the provided byte buffer could have only 2 available bytes: + * Warning: it is not guaranteed that all the available bytes will be represented as a single byte buffer + * e.g.: it could be 4 bytes available for read but the provided byte buffer could have only 2 available bytes: * in this case you have to invoke read again (with decreased [min] accordingly). * * @param min amount of bytes available for read, should be positive @@ -157,8 +158,8 @@ public fun ByteReadChannel.readAvailable(block: (ByteBuffer) -> Int): Int { * * If [min] is zero then the invocation will suspend until at least one byte available. * - * Warning: it is not guaranteed that all of remaining bytes will be represented as a single byte buffer - * eg: it could be 4 bytes available for read but the provided byte buffer could have only 2 remaining bytes: + * Warning: it is not guaranteed that all the remaining bytes will be represented as a single byte buffer + * e.g.: it could be 4 bytes available for read but the provided byte buffer could have only 2 remaining bytes: * in this case you have to invoke read again (with decreased [min] accordingly). * * It will fail with [EOFException] if not enough bytes ([availableForRead] < [min]) available diff --git a/ktor-server/ktor-server-core/common/src/io/ktor/server/plugins/Errors.kt b/ktor-server/ktor-server-core/common/src/io/ktor/server/plugins/Errors.kt index 8c672d512f0..a3f0dcbe5d9 100644 --- a/ktor-server/ktor-server-core/common/src/io/ktor/server/plugins/Errors.kt +++ b/ktor-server/ktor-server-core/common/src/io/ktor/server/plugins/Errors.kt @@ -15,14 +15,14 @@ import kotlin.reflect.* * Base exception to indicate that the request is not correct due to * wrong/missing request parameters, body content or header values. * Throwing this exception in a handler will lead to 400 Bad Request response - * unless a custom [io.ktor.plugins.StatusPages] handler registered. + * unless a custom [StatusPages](https://ktor.io/docs/server-status-pages.html) handler registered. */ public open class BadRequestException(message: String, cause: Throwable? = null) : Exception(message, cause) /** * This exception means that the requested resource is not found. * HTTP status 404 Not found will be replied when this exception is thrown and not caught. - * 404 status page could be configured by registering a custom [io.ktor.plugins.StatusPages] handler. + * 404 status page could be configured by registering a custom [StatusPages](https://ktor.io/docs/server-status-pages.html) handler. */ public class NotFoundException(message: String? = "Resource not found") : Exception(message) diff --git a/ktor-server/ktor-server-plugins/ktor-server-call-id/common/src/io/ktor/server/plugins/callid/CallId.kt b/ktor-server/ktor-server-plugins/ktor-server-call-id/common/src/io/ktor/server/plugins/callid/CallId.kt index d10c8743409..9d92973342d 100644 --- a/ktor-server/ktor-server-plugins/ktor-server-call-id/common/src/io/ktor/server/plugins/callid/CallId.kt +++ b/ktor-server/ktor-server-plugins/ktor-server-call-id/common/src/io/ktor/server/plugins/callid/CallId.kt @@ -247,7 +247,7 @@ private fun verifyCallIdAgainstDictionary(callId: String, dictionarySet: Set { /** - * Returns value for [key] or computes ans saves it if it's not found in the cache. + * Returns value for [key] or computes and saves it if it's not found in the cache. */ public suspend fun getOrCompute(key: K): V diff --git a/ktor-shared/ktor-serialization/ktor-serialization-kotlinx/ktor-serialization-kotlinx-cbor/common/src/io/ktor/serialization/kotlinx/cbor/CborSupport.kt b/ktor-shared/ktor-serialization/ktor-serialization-kotlinx/ktor-serialization-kotlinx-cbor/common/src/io/ktor/serialization/kotlinx/cbor/CborSupport.kt index 571f4bb4d58..33624fb4d95 100644 --- a/ktor-shared/ktor-serialization/ktor-serialization-kotlinx/ktor-serialization-kotlinx-cbor/common/src/io/ktor/serialization/kotlinx/cbor/CborSupport.kt +++ b/ktor-shared/ktor-serialization/ktor-serialization-kotlinx/ktor-serialization-kotlinx-cbor/common/src/io/ktor/serialization/kotlinx/cbor/CborSupport.kt @@ -25,7 +25,7 @@ public val DefaultCbor: Cbor = Cbor { /** * Registers the `application/cbor` (or another specified [contentType]) content type - * to the [ContentNegotiation] plugin using kotlinx.serialization. + * to the [KotlinxSerializationConverter] plugin using kotlinx.serialization. * * You can learn more from [Content negotiation and serialization](https://ktor.io/docs/serialization.html). * diff --git a/ktor-utils/common/src/io/ktor/util/Attributes.kt b/ktor-utils/common/src/io/ktor/util/Attributes.kt index 3bd25c290af..b4106c573f0 100644 --- a/ktor-utils/common/src/io/ktor/util/Attributes.kt +++ b/ktor-utils/common/src/io/ktor/util/Attributes.kt @@ -35,9 +35,7 @@ public data class AttributeKey @JvmOverloads constructor( } /** - * A version of [AttributeKey] that overrides [equals] and [hashCode] using [name] - * @param T is a type of the value stored in the attribute - * @param name is a name of the attribute + * Please use `AttributeKey` class instead. */ @Deprecated( "Please use `AttributeKey` class instead", @@ -47,7 +45,7 @@ public data class AttributeKey @JvmOverloads constructor( public typealias EquatableAttributeKey = AttributeKey /** - * Creates an attributes instance suitable for the particular platform + * Creates an [Attributes] instance suitable for the particular platform */ public expect fun Attributes(concurrent: Boolean = false): Attributes