Port all common documentations to jvm

okhttp/src/jvmMain/kotlin/okhttp3/CacheControl.kt

@@ -32,13 +32,32 @@ import okhttp3.internal.commonOnlyIfCached
 import okhttp3.internal.commonParse
 import okhttp3.internal.commonToString
 
+/**
+ * A Cache-Control header with cache directives from a server or client. These directives set policy
+ * on what responses can be stored, and which requests can be satisfied by those stored responses.
+ *
+ * See [RFC 7234, 5.2](https://tools.ietf.org/html/rfc7234#section-5.2).
+ */
 actual class CacheControl internal actual constructor(
+  /**
+   * In a response, this field's name "no-cache" is misleading. It doesn't prevent us from caching
+   * the response; it only means we have to validate the response with the origin server before
+   * returning it. We can do this with a conditional GET.
+   *
+   * In a request, it means do not use a cache to satisfy the request.
+   */
   @get:JvmName("noCache") actual val noCache: Boolean,
 
+  /** If true, this response should not be cached. */
   @get:JvmName("noStore") actual val noStore: Boolean,
 
+  /** The duration past the response's served date that it can be served without validation. */
   @get:JvmName("maxAgeSeconds") actual val maxAgeSeconds: Int,
 
+  /**
+   * The "s-maxage" directive is the max age for shared caches. Not to be confused with "max-age"
+   * for non-shared caches, As in Firefox and Chrome, this directive is not honored by this cache.
+   */
   @get:JvmName("sMaxAgeSeconds") actual val sMaxAgeSeconds: Int,
 
   actual val isPrivate: Boolean,
@@ -50,6 +69,12 @@ actual class CacheControl internal actual constructor(
 
   @get:JvmName("minFreshSeconds") actual val minFreshSeconds: Int,
 
+  /**
+   * This field's name "only-if-cached" is misleading. It actually means "do not use the network".
+   * It is set by a client who only wants to make a request if it can be fully satisfied by the
+   * cache. Cached responses that would require validation (ie. conditional gets) are not permitted
+   * if this header is set.
+   */
   @get:JvmName("onlyIfCached") actual val onlyIfCached: Boolean,
 
   @get:JvmName("noTransform") actual val noTransform: Boolean,
@@ -130,6 +155,7 @@ actual class CacheControl internal actual constructor(
 
   actual override fun toString(): String = commonToString()
 
+  /** Builds a `Cache-Control` request header. */
   actual class Builder {
     internal actual var noCache: Boolean = false
     internal actual var noStore: Boolean = false
@@ -140,16 +166,30 @@ actual class CacheControl internal actual constructor(
     internal actual var noTransform: Boolean = false
     internal actual var immutable: Boolean = false
 
+    /** Don't accept an unvalidated cached response. */
     actual fun noCache() = commonNoCache()
 
+    /** Don't store the server's response in any cache. */
     actual fun noStore() = commonNoStore()
 
+    /**
+     * Only accept the response if it is in the cache. If the response isn't cached, a `504
+     * Unsatisfiable Request` response will be returned.
+     */
     actual fun onlyIfCached() = commonOnlyIfCached()
 
+    /** Don't accept a transformed response. */
     actual fun noTransform() = commonNoTransform()
 
     actual fun immutable() = commonImmutable()
 
+    /**
+     * Sets the maximum age of a cached response. If the cache response's age exceeds [maxAge], it
+     * will not be used and a network request will be made.
+     *
+     * @param maxAge a non-negative integer. This is stored and transmitted with [TimeUnit.SECONDS]
+     *     precision; finer precision will be lost.
+     */
     actual fun maxAge(maxAge: Int, timeUnit: DurationUnit) = commonMaxAge(maxAge, timeUnit)
 
     actual fun maxStale(maxStale: Int, timeUnit: DurationUnit) = commonMaxStale(maxStale, timeUnit)
@@ -200,12 +240,25 @@ actual class CacheControl internal actual constructor(
   }
 
   actual companion object {
+    /**
+     * Cache control request directives that require network validation of responses. Note that such
+     * requests may be assisted by the cache via conditional GET requests.
+     */
     @JvmField
     actual val FORCE_NETWORK = commonForceNetwork()
 
+    /**
+     * Cache control request directives that uses the cache only, even if the cached response is
+     * stale. If the response isn't available in the cache or requires server validation, the call
+     * will fail with a `504 Unsatisfiable Request`.
+     */
     @JvmField
     actual val FORCE_CACHE = commonForceCache()
 
+    /**
+     * Returns the cache directives of [headers]. This honors both Cache-Control and Pragma headers
+     * if they are present.
+     */
     @JvmStatic
     actual fun parse(headers: Headers): CacheControl = commonParse(headers)
   }

okhttp/src/jvmMain/kotlin/okhttp3/Call.kt

@@ -12,14 +12,18 @@
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
- *
  */
 package okhttp3
 
 import okio.IOException
 import okio.Timeout
 
+/**
+ * A call is a request that has been prepared for execution. A call can be canceled. As this object
+ * represents a single request/response pair (stream), it cannot be executed twice.
+ */
 actual interface Call : Cloneable {
+  /** Returns the original request that initiated this call. */
   actual fun request(): Request
 
   /**
@@ -50,10 +54,26 @@ actual interface Call : Cloneable {
   @Throws(IOException::class)
   fun execute(): Response
 
+  /**
+   * Schedules the request to be executed at some point in the future.
+   *
+   * The [dispatcher][OkHttpClient.dispatcher] defines when the request will run: usually
+   * immediately unless there are several other requests currently being executed.
+   *
+   * This client will later call back `responseCallback` with either an HTTP response or a failure
+   * exception.
+   *
+   * @throws IllegalStateException when the call has already been executed.
+   */
   actual fun enqueue(responseCallback: Callback)
 
+  /** Cancels the request, if possible. Requests that are already complete cannot be canceled. */
   actual fun cancel()
 
+  /**
+   * Returns true if this call has been either [executed][execute] or [enqueued][enqueue]. It is an
+   * error to execute a call more than once.
+   */
   actual fun isExecuted(): Boolean
 
   actual fun isCanceled(): Boolean
@@ -67,6 +87,10 @@ actual interface Call : Cloneable {
    */
   fun timeout(): Timeout
 
+  /**
+   * Create a new, identical call to this one which can be enqueued or executed even if this call
+   * has already been.
+   */
   public actual override fun clone(): Call
 
   actual fun interface Factory {

okhttp/src/jvmMain/kotlin/okhttp3/Challenge.kt

@@ -24,13 +24,24 @@ import okhttp3.internal.commonEquals
 import okhttp3.internal.commonHashCode
 import okhttp3.internal.commonToString
 
+/**
+ * An [RFC 7235][rfc_7235] challenge.
+ *
+ * [rfc_7235]: https://tools.ietf.org/html/rfc7235
+ */
 actual class Challenge actual constructor(
+  /** Returns the authentication scheme, like `Basic`. */
   @get:JvmName("scheme") actual val scheme: String,
 
   authParams: Map<String?, String>
 ) {
+  /**
+   * Returns the auth params, including [realm] and [charset] if present, but as
+   * strings. The map's keys are lowercase and should be treated case-insensitively.
+   */
   @get:JvmName("authParams") actual val authParams: Map<String?, String>
 
+  /** Returns the protection space. */
   @get:JvmName("realm") actual val realm: String?
     get() = authParams["realm"]
 

okhttp/src/jvmMain/kotlin/okhttp3/Headers.kt

@@ -46,10 +46,27 @@ import okhttp3.internal.http.toHttpDateOrNull
 import okhttp3.internal.http.toHttpDateString
 import org.codehaus.mojo.animal_sniffer.IgnoreJRERequirement
 
+/**
+ * The header fields of a single HTTP message. Values are uninterpreted strings; use `Request` and
+ * `Response` for interpreted headers. This class maintains the order of the header fields within
+ * the HTTP message.
+ *
+ * This class tracks header values line-by-line. A field with multiple comma- separated values on
+ * the same line will be treated as a field with a single value by this class. It is the caller's
+ * responsibility to detect and split on commas if their field permits multiple values. This
+ * simplifies use of single-valued fields whose values routinely contain commas, such as cookies or
+ * dates.
+ *
+ * This class trims whitespace from values. It never returns values with leading or trailing
+ * whitespace.
+ *
+ * Instances of this class are immutable. Use [Builder] to create instances.
+ */
 @Suppress("NAME_SHADOWING")
 actual class Headers internal actual constructor(
   internal actual val namesAndValues: Array<String>
 ) : Iterable<Pair<String, String>> {
+  /** Returns the last value corresponding to the specified field, or null. */
   actual operator fun get(name: String): String? = commonHeadersGet(namesAndValues, name)
 
   /**
@@ -67,6 +84,7 @@ actual class Headers internal actual constructor(
     return getDate(name)?.toInstant()
   }
 
+  /** Returns the number of field values. */
   @get:JvmName("size") actual val size: Int
     get() = namesAndValues.size / 2
 
@@ -77,10 +95,13 @@ actual class Headers internal actual constructor(
       level = DeprecationLevel.ERROR)
   fun size(): Int = size
 
+  /** Returns the field at `position`. */
   actual fun name(index: Int): String = commonName(index)
 
+  /** Returns the value at `index`. */
   actual fun value(index: Int): String = commonValue(index)
 
+  /** Returns an immutable case-insensitive set of header names. */
   actual fun names(): Set<String> {
     val result = TreeSet(String.CASE_INSENSITIVE_ORDER)
     for (i in 0 until size) {
@@ -89,6 +110,7 @@ actual class Headers internal actual constructor(
     return Collections.unmodifiableSet(result)
   }
 
+  /** Returns an immutable list of the header values for `name`. */
   actual fun values(name: String): List<String> = commonValues(name)
 
   /**
@@ -112,10 +134,57 @@ actual class Headers internal actual constructor(
 
   actual fun newBuilder(): Builder = commonNewBuilder()
 
+  /**
+   * Returns true if `other` is a `Headers` object with the same headers, with the same casing, in
+   * the same order. Note that two headers instances may be *semantically* equal but not equal
+   * according to this method. In particular, none of the following sets of headers are equal
+   * according to this method:
+   *
+   * 1. Original
+   * ```
+   * Content-Type: text/html
+   * Content-Length: 50
+   * ```
+   *
+   * 2. Different order
+   *
+   * ```
+   * Content-Length: 50
+   * Content-Type: text/html
+   * ```
+   *
+   * 3. Different case
+   *
+   * ```
+   * content-type: text/html
+   * content-length: 50
+   * ```
+   *
+   * 4. Different values
+   *
+   * ```
+   * Content-Type: text/html
+   * Content-Length: 050
+   * ```
+   *
+   * Applications that require semantically equal headers should convert them into a canonical form
+   * before comparing them for equality.
+   */
   actual override fun equals(other: Any?): Boolean = commonEquals(other)
 
   override fun hashCode(): Int = commonHashCode()
 
+  /**
+   * Returns header names and values. The names and values are separated by `: ` and each pair is
+   * followed by a newline character `\n`.
+   *
+   * Since OkHttp 5 this redacts these sensitive headers:
+   *
+   *  * `Authorization`
+   *  * `Cookie`
+   *  * `Proxy-Authorization`
+   *  * `Set-Cookie`
+   */
   actual override fun toString(): String = commonToString()
 
   fun toMultimap(): Map<String, List<String>> {
@@ -164,6 +233,9 @@ actual class Headers internal actual constructor(
       add(line.substring(0, index).trim(), line.substring(index + 1))
     }
 
+    /**
+     * Add a header with the specified name and value. Does validation of header names and values.
+     */
     actual fun add(name: String, value: String) = commonAdd(name, value)
 
     /**
@@ -175,6 +247,9 @@ actual class Headers internal actual constructor(
       addLenient(name, value)
     }
 
+    /**
+     * Adds all headers from an existing collection.
+     */
     actual fun addAll(headers: Headers) = commonAddAll(headers)
 
     /**
@@ -224,6 +299,10 @@ actual class Headers internal actual constructor(
   }
 
   actual companion object {
+    /**
+     * Returns headers for the alternating header names and values. There must be an even number of
+     * arguments, and they must alternate between header names and values.
+     */
     @JvmStatic
     @JvmName("of")
     actual fun headersOf(vararg namesAndValues: String): Headers = commonHeadersOf(*namesAndValues)
@@ -237,6 +316,7 @@ actual class Headers internal actual constructor(
       return headersOf(*namesAndValues)
     }
 
+    /** Returns headers for the header names and values in the [Map]. */
     @JvmStatic
     @JvmName("of")
     actual fun Map<String, String>.toHeaders(): Headers = commonToHeaders()