fixup! fixup! KTOR-6501 Add HttpClientEngine api docs

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

@@ -19,7 +19,54 @@ internal val ENGINE_CAPABILITIES_KEY =
 public val DEFAULT_CAPABILITIES: Set<HttpClientEngineCapability<*>> = setOf(HttpTimeoutCapability)
 
 /**
- * Capability required by request to be supported by [HttpClientEngine] with [T] representing type of the capability
- * configuration.
+ * Represents a capability that an [HttpClientEngine] can support, with [T] representing the type
+ * of configuration or metadata associated with the capability.
+ *
+ * Capabilities are used to declare optional features or behaviors that an engine may support,
+ * such as WebSocket communication, HTTP/2, or custom timeouts. They enable plugins and request
+ * builders to configure engine-specific functionality by associating a capability with a
+ * specific configuration.
+ *
+ * Capabilities can be set on a per-request basis using the `HttpRequestBuilder.setCapability` method,
+ * allowing users to configure engine-specific behavior for individual requests.
+ *
+ * @param T The type of the configuration or metadata associated with this capability.
+ *
+ * Example:
+ * Suppose you have a custom capability for WebSocket support that requires a specific configuration:
+ * ```kotlin
+ * object WebSocketCapability : HttpClientEngineCapability<WebSocketConfig>
+ *
+ * data class WebSocketConfig(val maxFrameSize: Int, val pingIntervalMillis: Long)
+ * ```
+ *
+ * Setting a capability in a request:
+ * ```kotlin
+ * client.request {
+ *     setCapability(WebSocketCapability, WebSocketConfig(
+ *         maxFrameSize = 65536,
+ *         pingIntervalMillis = 30000
+ *     ))
+ * }
+ * ```
+ *
+ * Engine Example:
+ * A custom engine implementation can declare support for specific capabilities in its `supportedCapabilities` property:
+ * ```kotlin
+ * override val supportedCapabilities: Set<HttpClientEngineCapability<*>> = setOf(WebSocketCapability)
+ * ```
+ *
+ * Plugin Integration Example:
+ * Plugins use capabilities to interact with engine-specific features. For example:
+ * ```kotlin
+ * if (engine.supportedCapabilities.contains(WebSocketCapability)) {
+ *     // Configure WebSocket behavior if supported by the engine
+ * }
+ * ```
+ *
+ * When creating a custom capability:
+ * - Define a singleton object implementing `HttpClientEngineCapability`.
+ * - Use the type parameter [T] to provide the associated configuration type or metadata.
+ * - Ensure that engines supporting the capability handle the associated configuration properly.
  */
 public interface HttpClientEngineCapability<T>