From e458bd0a90b8852f5c252d078b34711fea951455 Mon Sep 17 00:00:00 2001 From: Jesse Wilson Date: Sat, 30 Mar 2019 17:28:37 -0400 Subject: [PATCH] Configure Dokka --- build.gradle | 14 ++++++++ .../java/okhttp3/dnsoverhttps/DnsOverHttps.kt | 7 ++-- okhttp/src/main/java/okhttp3/Authenticator.kt | 18 +++++----- okhttp/src/main/java/okhttp3/Cache.kt | 23 ++++++------ .../main/java/okhttp3/CertificatePinner.kt | 28 ++++++++------- okhttp/src/main/java/okhttp3/Challenge.kt | 2 +- okhttp/src/main/java/okhttp3/CipherSuite.kt | 17 +++++---- okhttp/src/main/java/okhttp3/Connection.kt | 16 ++++----- .../src/main/java/okhttp3/ConnectionSpec.kt | 10 +++--- okhttp/src/main/java/okhttp3/Cookie.kt | 6 ++-- okhttp/src/main/java/okhttp3/CookieJar.kt | 7 ++-- okhttp/src/main/java/okhttp3/HttpUrl.kt | 36 +++++++++---------- okhttp/src/main/java/okhttp3/MediaType.kt | 6 ++-- okhttp/src/main/java/okhttp3/OkHttpClient.kt | 33 ++++++++--------- okhttp/src/main/java/okhttp3/Protocol.kt | 21 ++++++----- okhttp/src/main/java/okhttp3/Route.kt | 4 ++- okhttp/src/main/java/okhttp3/WebSocket.kt | 7 ++-- 17 files changed, 140 insertions(+), 115 deletions(-) diff --git a/build.gradle b/build.gradle index eb85ef693..95ff6c0b9 100644 --- a/build.gradle +++ b/build.gradle @@ -40,6 +40,7 @@ buildscript { classpath 'com.vanniktech:gradle-maven-publish-plugin:0.8.0' classpath 'net.ltgt.gradle:gradle-errorprone-plugin:0.7.1' classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${versions.kotlin}" + classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.9.18" } repositories { @@ -60,6 +61,9 @@ allprojects { repositories { mavenCentral() + maven { + url 'https://dl.bintray.com/kotlin/dokka' + } } task downloadDependencies() { @@ -119,6 +123,16 @@ subprojects { project -> errorproneJavac 'com.google.errorprone:javac:9+181-r4173-1' errorprone 'com.google.errorprone:error_prone_core:2.3.3' } + + apply plugin: 'org.jetbrains.dokka' + dokka { + reportUndocumented = false + skipDeprecated = true + packageOptions { + prefix = "okhttp3.internal" + suppress = true + } + } } tasks.wrapper { diff --git a/okhttp-dnsoverhttps/src/main/java/okhttp3/dnsoverhttps/DnsOverHttps.kt b/okhttp-dnsoverhttps/src/main/java/okhttp3/dnsoverhttps/DnsOverHttps.kt index a0868dc18..9b97d4b4a 100644 --- a/okhttp-dnsoverhttps/src/main/java/okhttp3/dnsoverhttps/DnsOverHttps.kt +++ b/okhttp-dnsoverhttps/src/main/java/okhttp3/dnsoverhttps/DnsOverHttps.kt @@ -35,9 +35,7 @@ import java.util.ArrayList import java.util.concurrent.CountDownLatch /** - * DNS over HTTPS implementation. - * - * Implementation of https://tools.ietf.org/html/draft-ietf-doh-dns-over-https-13 + * [DNS over HTTPS implementation][[doh_spec]]. * *
A DNS API client encodes a single DNS query into an HTTP request * using either the HTTP GET or POST method and the other requirements @@ -46,10 +44,11 @@ import java.util.concurrent.CountDownLatch * *

Warning: This is a non-final API.

* - * * As of OkHttp 3.14, this feature is an unstable preview: the API is subject to change, * and the implementation is incomplete. We expect that OkHttp 4.0 or 4.1 will finalize this API. * Until then, expect API and behavior changes when you update your OkHttp dependency.** + * + * [doh_spec]: https://tools.ietf.org/html/draft-ietf-doh-dns-over-https-13 */ class DnsOverHttps internal constructor(builder: Builder) : Dns { private val client: OkHttpClient = diff --git a/okhttp/src/main/java/okhttp3/Authenticator.kt b/okhttp/src/main/java/okhttp3/Authenticator.kt index 3e0eecd42..62c3f8877 100644 --- a/okhttp/src/main/java/okhttp3/Authenticator.kt +++ b/okhttp/src/main/java/okhttp3/Authenticator.kt @@ -22,15 +22,14 @@ import java.io.IOException * **reactive** authentication after receiving a challenge from either an origin web server or proxy * server. * - * Preemptive Authentication - * ------------------------- + * ## Preemptive Authentication * * To make HTTPS calls using an HTTP proxy server OkHttp must first negotiate a connection with - * the proxy. This proxy connection is called a "TLS Tunnel" and is specified by [RFC - * 2817](https://tools.ietf.org/html/rfc2817). The HTTP CONNECT request that creates this tunnel - * connection is special: it does not participate in any [interceptors][Interceptor] or [event - * listeners][EventListener]. It doesn't include the motivating request's HTTP headers or even its - * full URL; only the target server's hostname is sent to the proxy. + * the proxy. This proxy connection is called a "TLS Tunnel" and is specified by + * [RFC 2817][rfc_2817]. The HTTP CONNECT request that creates this tunnel connection is special: it + * does not participate in any [interceptors][Interceptor] or [event listeners][EventListener]. It + * doesn't include the motivating request's HTTP headers or even its full URL; only the target + * server's hostname is sent to the proxy. * * Prior to sending any CONNECT request OkHttp always calls the proxy authenticator so that it may * prepare preemptive authentication. OkHttp will call [authenticate] with a fake `HTTP/1.1 407 @@ -50,8 +49,7 @@ import java.io.IOException * return null; // Didn't find a preemptive auth scheme. * ``` * - * Reactive Authentication - * ----------------------- + * ## Reactive Authentication * * Implementations authenticate by returning a follow-up request that includes an authorization * header, or they may decline the challenge by returning null. In this case the unauthenticated @@ -94,6 +92,8 @@ import java.io.IOException * * Applications may configure OkHttp with an authenticator for origin servers, or proxy servers, * or both. + * + * [rfc_2817]: https://tools.ietf.org/html/rfc2817 */ interface Authenticator { /** diff --git a/okhttp/src/main/java/okhttp3/Cache.kt b/okhttp/src/main/java/okhttp3/Cache.kt index 6c8804cdd..094f81f23 100644 --- a/okhttp/src/main/java/okhttp3/Cache.kt +++ b/okhttp/src/main/java/okhttp3/Cache.kt @@ -52,8 +52,7 @@ import java.util.NoSuchElementException * Caches HTTP and HTTPS responses to the filesystem so they may be reused, saving time and * bandwidth. * - * Cache Optimization - * ------------------ + * ## Cache Optimization * * To measure cache effectiveness, this class tracks three statistics: * @@ -69,11 +68,10 @@ import java.util.NoSuchElementException * is still valid. Such responses increment both the network count and hit count. * * The best way to improve the cache hit rate is by configuring the web server to return cacheable - * responses. Although this client honors all [HTTP/1.1 (RFC - * 7234)](http://tools.ietf.org/html/rfc7234) cache headers, it doesn't cache partial responses. + * responses. Although this client honors all [HTTP/1.1 (RFC 7234)][rfc_7234] cache headers, it + * doesn't cache partial responses. * - * Force a Network Response - * ------------------------ + * ## Force a Network Response * * In some situations, such as after a user clicks a 'refresh' button, it may be necessary to skip * the cache, and fetch data directly from the server. To force a full refresh, add the `no-cache` @@ -98,8 +96,7 @@ import java.util.NoSuchElementException * .build(); * ``` * - * Force a Cache Response - * ---------------------- + * ## Force a Cache Response * * Sometimes you'll want to show resources if they are available immediately, but not otherwise. * This can be used so your application can show *something* while waiting for the latest data to be @@ -137,6 +134,8 @@ import java.util.NoSuchElementException * The [CacheControl] class can configure request caching directives and parse response caching * directives. It even offers convenient constants [CacheControl.FORCE_NETWORK] and * [CacheControl.FORCE_CACHE] that address the use cases above. + * + * [rfc_7234]: http://tools.ietf.org/html/rfc7234 */ class Cache internal constructor( directory: File, @@ -308,13 +307,13 @@ class Cache internal constructor( } /** - * Returns an iterator over the URLs in this cache. This iterator doesn't throw `ConcurrentModificationException`, but if new responses are added while iterating, their URLs + * Returns an iterator over the URLs in this cache. This iterator doesn't throw + * `ConcurrentModificationException`, but if new responses are added while iterating, their URLs * will not be returned. If existing responses are evicted during iteration, they will be absent * (unless they were already returned). * - * - * The iterator supports [Iterator.remove]. Removing a URL from the iterator evicts - * the corresponding response from the cache. Use this to evict selected responses. + * The iterator supports [MutableIterator.remove]. Removing a URL from the iterator evicts the + * corresponding response from the cache. Use this to evict selected responses. */ @Throws(IOException::class) fun urls(): MutableIterator { diff --git a/okhttp/src/main/java/okhttp3/CertificatePinner.kt b/okhttp/src/main/java/okhttp3/CertificatePinner.kt index 412bf3212..44a7b716c 100644 --- a/okhttp/src/main/java/okhttp3/CertificatePinner.kt +++ b/okhttp/src/main/java/okhttp3/CertificatePinner.kt @@ -27,19 +27,16 @@ import javax.net.ssl.SSLPeerUnverifiedException * Constrains which certificates are trusted. Pinning certificates defends against attacks on * certificate authorities. It also prevents connections through man-in-the-middle certificate * authorities either known or unknown to the application's user. + * This class currently pins a certificate's Subject Public Key Info as described on + * [Adam Langley's Weblog][langley]. Pins are either base64 SHA-256 hashes as in + * [HTTP Public Key Pinning (HPKP)][rfc_7469] or SHA-1 base64 hashes as in Chromium's + * [static certificates][static_certificates]. * - * This class currently pins a certificate's Subject Public Key Info as described on [Adam Langley's - * Weblog](http://goo.gl/AIx3e5). Pins are either base64 SHA-256 hashes as in [HTTP Public Key - * Pinning (HPKP)](http://tools.ietf.org/html/rfc7469) or SHA-1 base64 hashes as in Chromium's - * [static certificates](http://goo.gl/XDh6je). - * - * Setting up Certificate Pinning - * ------------------------------ + * ## Setting up Certificate Pinning * * The easiest way to pin a host is turn on pinning with a broken configuration and read the * expected configuration when the connection fails. Be sure to do this on a trusted network, and - * without man-in-the-middle tools like [Charles](http://charlesproxy.com) or - * [Fiddler](http://fiddlertool.com). + * without man-in-the-middle tools like [Charles][charles] or [Fiddler][fiddler]. * * For example, to pin `https://publicobject.com`, start with a broken configuration: * @@ -104,8 +101,7 @@ import javax.net.ssl.SSLPeerUnverifiedException * For example: `*.example.com` pinned with `pin1` and `a.example.com` pinned with `pin2`, to check * `a.example.com` both `pin1` and `pin2` will be used. * - * Warning: Certificate Pinning is Dangerous! - * ------------------------------------------ + * ## Warning: Certificate Pinning is Dangerous! * * Pinning certificates limits your server team's abilities to update their TLS certificates. By * pinning certificates, you take on additional operational complexity and limit your ability to @@ -117,8 +113,14 @@ import javax.net.ssl.SSLPeerUnverifiedException * [CertificatePinner] can not be used to pin self-signed certificate if such certificate is not * accepted by [javax.net.ssl.TrustManager]. * - * @see [OWASP: Certificate and Public Key - * Pinning](https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning) + * See also [OWASP: Certificate and Public Key Pinning][owasp]. + * + * [charles]: http://charlesproxy.com + * [fiddler]: http://fiddlertool.com + * [langley]: http://goo.gl/AIx3e5 + * [owasp]: https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning + * [rfc_7469]: http://tools.ietf.org/html/rfc7469 + * [static_certificates]: http://goo.gl/XDh6je */ class CertificatePinner internal constructor( private val pins: Set, diff --git a/okhttp/src/main/java/okhttp3/Challenge.kt b/okhttp/src/main/java/okhttp3/Challenge.kt index 52dc16e2a..6871bbd9e 100644 --- a/okhttp/src/main/java/okhttp3/Challenge.kt +++ b/okhttp/src/main/java/okhttp3/Challenge.kt @@ -46,7 +46,7 @@ class Challenge( return Challenge(scheme, authParams) } - /** Returns the authentication scheme, like [Basic]. */ + /** Returns the authentication scheme, like `Basic`. */ fun scheme() = scheme /** diff --git a/okhttp/src/main/java/okhttp3/CipherSuite.kt b/okhttp/src/main/java/okhttp3/CipherSuite.kt index 7bd143692..0317ca71d 100644 --- a/okhttp/src/main/java/okhttp3/CipherSuite.kt +++ b/okhttp/src/main/java/okhttp3/CipherSuite.kt @@ -16,21 +16,24 @@ package okhttp3 /** - * [TLS cipher suites](https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml). + * [TLS cipher suites][iana_tls_parameters]. * * **Not all cipher suites are supported on all platforms.** As newer cipher suites are created (for * stronger privacy, better performance, etc.) they will be adopted by the platform and then exposed * here. Cipher suites that are not available on either Android (through API level 24) or Java * (through JDK 9) are omitted for brevity. * - * See [Android SSLEngine](https://developer.android.com/reference/javax/net/ssl/SSLEngine.html) - * which lists the cipher suites supported by Android. + * See [Android SSLEngine][sslengine] which lists the cipher suites supported by Android. * - * See [JDK 10 Providers](https://docs.oracle.com/javase/10/security/oracle-providers.htm) - * which lists the cipher suites supported by Oracle. + * See [JDK Providers][oracle_providers] which lists the cipher suites supported by Oracle. * - * See [NativeCrypto.java](https://github.com/google/conscrypt/blob/master/common/src/main/java/org/conscrypt/NativeCrypto.java) - * from Conscrypt, which lists the cipher suites supported by Conscrypt. + * See [NativeCrypto.java][conscrypt_providers] which lists the cipher suites supported by + * Conscrypt. + * + * [iana_tls_parameters]: https://www.iana.org/assignments/tls-parameters/tls-parameters.xhtml + * [sslengine]: https://developer.android.com/reference/javax/net/ssl/SSLEngine.html + * [oracle_providers]: https://docs.oracle.com/javase/10/security/oracle-providers.htm + * [conscrypt_providers]: https://github.com/google/conscrypt/blob/master/common/src/main/java/org/conscrypt/NativeCrypto.java */ class CipherSuite private constructor( private val javaName: String diff --git a/okhttp/src/main/java/okhttp3/Connection.kt b/okhttp/src/main/java/okhttp3/Connection.kt index f3075eda1..20dda3de9 100644 --- a/okhttp/src/main/java/okhttp3/Connection.kt +++ b/okhttp/src/main/java/okhttp3/Connection.kt @@ -23,14 +23,13 @@ import java.net.Socket * HTTP request/response exchanges. Connections may be direct to the origin server or via a proxy. * * Typically instances of this class are created, connected and exercised automatically by the HTTP - * client. Applications may use this class to monitor HTTP connections as members of a [connection - * pool][ConnectionPool]. + * client. Applications may use this class to monitor HTTP connections as members of a + * [connection pool][ConnectionPool]. * * Do not confuse this class with the misnamed `HttpURLConnection`, which isn't so much a connection * as a single request/response exchange. * - * Modern TLS - * ---------- + * ## Modern TLS * * There are trade-offs when selecting which options to include when negotiating a secure connection * to a remote host. Newer TLS options are quite useful: @@ -45,8 +44,7 @@ import java.net.Socket * avoiding these options entirely, this class allows a connection to be attempted with modern * options and then retried without them should the attempt fail. * - * Connection Reuse - * ---------------- + * ## Connection Reuse * * Each connection can carry a varying number of streams, depending on the underlying protocol being * used. HTTP/1.x connections can carry either zero or one streams. HTTP/2 connections can carry any @@ -73,9 +71,9 @@ interface Connection { fun route(): Route /** - * Returns the socket that this connection is using. Returns an [SSL - * socket][javax.net.ssl.SSLSocket] if this connection is HTTPS. If this is an HTTP/2 connection - * the socket may be shared by multiple concurrent calls. + * Returns the socket that this connection is using. Returns an + * [SSL socket][javax.net.ssl.SSLSocket] if this connection is HTTPS. If this is an HTTP/2 + * connection the socket may be shared by multiple concurrent calls. */ fun socket(): Socket diff --git a/okhttp/src/main/java/okhttp3/ConnectionSpec.kt b/okhttp/src/main/java/okhttp3/ConnectionSpec.kt index de12bcad0..f6c0a197b 100644 --- a/okhttp/src/main/java/okhttp3/ConnectionSpec.kt +++ b/okhttp/src/main/java/okhttp3/ConnectionSpec.kt @@ -40,9 +40,9 @@ import javax.net.ssl.SSLSocket * The configuration of each spec changes with each OkHttp release. This is annoying: upgrading * your OkHttp library can break connectivity to certain web servers! But it’s a necessary annoyance * because the TLS ecosystem is dynamic and staying up to date is necessary to stay secure. See - * [OkHttp's TLS - * Configuration History](https://github.com/square/okhttp/wiki/TLS-Configuration-History) to track - * these changes. + * [OkHttp's TLS Configuration History][tls_history] to track these changes. + * + * [tls_history]: https://github.com/square/okhttp/wiki/TLS-Configuration-History */ class ConnectionSpec internal constructor(builder: Builder) { val isTls: Boolean = builder.tls @@ -196,7 +196,7 @@ class ConnectionSpec internal constructor(builder: Builder) { this.cipherSuites = null } - fun cipherSuites(vararg cipherSuites: CipherSuite) = apply { + fun cipherSuites(vararg cipherSuites: CipherSuite): Builder = apply { require(tls) { "no cipher suites for cleartext connections" } val strings = cipherSuites.map(CipherSuite::javaName).toTypedArray() return cipherSuites(*strings) @@ -214,7 +214,7 @@ class ConnectionSpec internal constructor(builder: Builder) { this.tlsVersions = null } - fun tlsVersions(vararg tlsVersions: TlsVersion) = apply { + fun tlsVersions(vararg tlsVersions: TlsVersion): Builder = apply { require(tls) { "no TLS versions for cleartext connections" } val strings = tlsVersions.map(TlsVersion::javaName).toTypedArray() diff --git a/okhttp/src/main/java/okhttp3/Cookie.kt b/okhttp/src/main/java/okhttp3/Cookie.kt index c0dbcdbbf..6c164bc5f 100644 --- a/okhttp/src/main/java/okhttp3/Cookie.kt +++ b/okhttp/src/main/java/okhttp3/Cookie.kt @@ -34,8 +34,10 @@ import java.util.regex.Pattern /** * An [RFC 6265](http://tools.ietf.org/html/rfc6265) Cookie. * - * This class doesn't support additional attributes on cookies, like [Chromium's Priority=HIGH - * extension](https://code.google.com/p/chromium/issues/detail?id=232693). + * This class doesn't support additional attributes on cookies, like + * [Chromium's Priority=HIGH extension][chromium_extension]. + * + * [chromium_extension]: https://code.google.com/p/chromium/issues/detail?id=232693 */ class Cookie private constructor( private val name: String, diff --git a/okhttp/src/main/java/okhttp3/CookieJar.kt b/okhttp/src/main/java/okhttp3/CookieJar.kt index a95e4fb19..d270f25a9 100644 --- a/okhttp/src/main/java/okhttp3/CookieJar.kt +++ b/okhttp/src/main/java/okhttp3/CookieJar.kt @@ -24,9 +24,10 @@ package okhttp3 * * As persistence, implementations of this interface must also provide storage of cookies. Simple * implementations may store cookies in memory; sophisticated ones may use the file system or - * database to hold accepted cookies. The [cookie storage - * model](https://tools.ietf.org/html/rfc6265#section-5.3) specifies policies for updating and - * expiring cookies. + * database to hold accepted cookies. The [cookie storage model][rfc_6265_53] specifies policies for + * updating and expiring cookies. + * + * [rfc_6265_53]: https://tools.ietf.org/html/rfc6265#section-5.3 */ interface CookieJar { /** diff --git a/okhttp/src/main/java/okhttp3/HttpUrl.kt b/okhttp/src/main/java/okhttp3/HttpUrl.kt index 5def5a854..4fc26196e 100644 --- a/okhttp/src/main/java/okhttp3/HttpUrl.kt +++ b/okhttp/src/main/java/okhttp3/HttpUrl.kt @@ -89,8 +89,7 @@ import java.util.LinkedHashSet * https://www.youtube.com/watch?v=cbP2N1BQdYc * ``` * - * What's in a URL? - * ---------------- + * ## What's in a URL? * * A URL has several components. * @@ -98,7 +97,7 @@ import java.util.LinkedHashSet * * Sometimes referred to as *protocol*, A URL's scheme describes what mechanism should be used to * retrieve the resource. Although URLs have many schemes (`mailto`, `file`, `ftp`), this class only - * supports `http` and `https`. Use [ java.net.URI][URI] for URLs with arbitrary schemes. + * supports `http` and `https`. Use [java.net.URI][URI] for URLs with arbitrary schemes. * * ### Username and Password * @@ -127,16 +126,16 @@ import java.util.LinkedHashSet * ### Path * * The path identifies a specific resource on the host. Paths have a hierarchical structure like - * "/square/okhttp/issues/1486" and decompose into a list of segments like ["square", "okhttp", - * "issues", "1486"]. + * "/square/okhttp/issues/1486" and decompose into a list of segments like `["square", "okhttp", + * "issues", "1486"]`. * * This class offers methods to compose and decompose paths by segment. It composes each path * from a list of segments by alternating between "/" and the encoded segment. For example the - * segments ["a", "b"] build "/a/b" and the segments ["a", "b", ""] build "/a/b/". + * segments `["a", "b"]` build "/a/b" and the segments `["a", "b", ""]` build "/a/b/". * * If a path's last segment is the empty string then the path ends with "/". This class always * builds non-empty paths: if the path is omitted it defaults to "/". The default path's segment - * list is a single empty string: [""]. + * list is a single empty string: `[""]`. * * ### Query * @@ -150,8 +149,7 @@ import java.util.LinkedHashSet * The fragment is optional: it can be null, empty, or non-empty. Unlike host, port, path, and * query the fragment is not sent to the webserver: it's private to the client. * - * Encoding - * -------- + * ## Encoding * * Each component must be encoded before it is embedded in the complete URL. As we saw above, the * string `cute #puppies` is encoded as `cute%20%23puppies` when used as a query parameter value. @@ -191,22 +189,20 @@ import java.util.LinkedHashSet * Hostnames have different requirements and use a different encoding scheme. It consists of IDNA * mapping and Punycode encoding. * - * In order to avoid confusion and discourage phishing attacks, [IDNA - * Mapping](http://www.unicode.org/reports/tr46/#ToASCII) transforms names to avoid confusing - * characters. This includes basic case folding: transforming shouting `SQUARE.COM` into cool and - * casual `square.com`. It also handles more exotic characters. For example, the Unicode trademark - * sign (™) could be confused for the letters "TM" in `http://ho™mail.com`. To mitigate this, the - * single character (™) maps to the string (tm). There is similar policy for all of the 1.1 million - * Unicode code points. Note that some code points such as "\ud83c\udf69" are not mapped and cannot - * be used in a hostname. + * In order to avoid confusion and discourage phishing attacks, [IDNA Mapping][idna] transforms + * names to avoid confusing characters. This includes basic case folding: transforming shouting + * `SQUARE.COM` into cool and casual `square.com`. It also handles more exotic characters. For + * example, the Unicode trademark sign (™) could be confused for the letters "TM" in + * `http://ho™mail.com`. To mitigate this, the single character (™) maps to the string (tm). There + * is similar policy for all of the 1.1 million Unicode code points. Note that some code points such + * as "\ud83c\udf69" are not mapped and cannot be used in a hostname. * * [Punycode](http://ietf.org/rfc/rfc3492.txt) converts a Unicode string to an ASCII string to make * international domain names work everywhere. For example, "σ" encodes as "xn--4xa". The encoded * string is not human readable, but can be used with classes like [InetAddress] to establish * connections. * - * Why another URL model? - * ---------------------- + * ## Why another URL model? * * Java includes both [java.net.URL][URL] and [java.net.URI][URI]. We offer a new URL * model to address problems that the others don't. @@ -287,6 +283,8 @@ import java.util.LinkedHashSet * This class has a modern API. It avoids punitive checked exceptions: [get] throws * [IllegalArgumentException] on invalid input or [parse] returns null if the input is an invalid * URL. You can even be explicit about whether each component has been encoded already. + * + * [idna]: http://www.unicode.org/reports/tr46/#ToASCII */ class HttpUrl internal constructor(builder: Builder) { diff --git a/okhttp/src/main/java/okhttp3/MediaType.kt b/okhttp/src/main/java/okhttp3/MediaType.kt index 56cbc8c92..6644c0c63 100644 --- a/okhttp/src/main/java/okhttp3/MediaType.kt +++ b/okhttp/src/main/java/okhttp3/MediaType.kt @@ -20,8 +20,10 @@ import java.util.Locale import java.util.regex.Pattern /** - * An [RFC 2045](http://tools.ietf.org/html/rfc2045) Media Type, appropriate to describe the - * content type of an HTTP request or response body. + * An [RFC 2045][rfc_2045] Media Type, appropriate to describe the content type of an HTTP request + * or response body. + * + * [rfc_2045]: http://tools.ietf.org/html/rfc2045 */ class MediaType private constructor( private val mediaType: String, diff --git a/okhttp/src/main/java/okhttp3/OkHttpClient.kt b/okhttp/src/main/java/okhttp3/OkHttpClient.kt index e747ebd77..d21288202 100644 --- a/okhttp/src/main/java/okhttp3/OkHttpClient.kt +++ b/okhttp/src/main/java/okhttp3/OkHttpClient.kt @@ -49,8 +49,7 @@ import kotlin.DeprecationLevel.ERROR /** * Factory for [calls][Call], which can be used to send HTTP requests and read their responses. * - * OkHttpClients Should Be Shared - * ------------------------------ + * ## OkHttpClients Should Be Shared * * OkHttp performs best when you create a single `OkHttpClient` instance and reuse it for all of * your HTTP calls. This is because each client holds its own connection pool and thread pools. @@ -74,8 +73,7 @@ import kotlin.DeprecationLevel.ERROR * .build(); * ``` * - * Customize Your Client With newBuilder() - * --------------------------------------- + * ## Customize Your Client With newBuilder() * * You can customize a shared OkHttpClient instance with [newBuilder]. This builds a client that * shares the same connection pool, thread pools, and configuration. Use the builder methods to @@ -90,8 +88,7 @@ import kotlin.DeprecationLevel.ERROR * Response response = eagerClient.newCall(request).execute(); * ``` * - * Shutdown Isn't Necessary - * ------------------------ + * ## Shutdown Isn't Necessary * * The threads and connections that are held will be released automatically if they remain idle. But * if you are writing a application that needs to aggressively release unused resources you may do @@ -454,8 +451,8 @@ open class OkHttpClient internal constructor( * If the server does not respond to each ping with a pong within `interval`, this client will * assume that connectivity has been lost. When this happens on a web socket the connection is * canceled and its listener is [notified][WebSocketListener.onFailure]. When it happens on an - * HTTP/2 connection the connection is closed and any calls it is carrying [will fail with an - * IOException][java.io.IOException]. + * HTTP/2 connection the connection is closed and any calls it is carrying + * [will fail with an IOException][java.io.IOException]. * * The default value of 0 disables client-initiated pings. */ @@ -471,8 +468,8 @@ open class OkHttpClient internal constructor( * If the server does not respond to each ping with a pong within `interval`, this client will * assume that connectivity has been lost. When this happens on a web socket the connection is * canceled and its listener is [notified][WebSocketListener.onFailure]. When it happens on an - * HTTP/2 connection the connection is closed and any calls it is carrying [will fail with an - * IOException][java.io.IOException]. + * HTTP/2 connection the connection is closed and any calls it is carrying + * [will fail with an IOException][java.io.IOException]. * * The default value of 0 disables client-initiated pings. */ @@ -694,20 +691,24 @@ open class OkHttpClient internal constructor( * * The following protocols are currently supported: * - * * [http/1.1](http://www.w3.org/Protocols/rfc2616/rfc2616.html) - * * [h2](https://tools.ietf.org/html/rfc7540) - * * [h2 with prior knowledge(cleartext only)](https://tools.ietf.org/html/rfc7540#section-3.4) + * * [http/1.1][rfc_2616] + * * [h2][rfc_7540] + * * [h2 with prior knowledge(cleartext only)][rfc_7540_34] * * **This is an evolving set.** Future releases include support for transitional * protocols. The http/1.1 transport will never be dropped. * - * If multiple protocols are specified, - * [ALPN](http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg) will be used to negotiate - * a transport. Protocol negotiation is only attempted for HTTPS URLs. + * If multiple protocols are specified, [ALPN][alpn] will be used to negotiate a transport. + * Protocol negotiation is only attempted for HTTPS URLs. * * [Protocol.HTTP_1_0] is not supported in this set. Requests are initiated with `HTTP/1.1`. If * the server responds with `HTTP/1.0`, that will be exposed by [Response.protocol]. * + * [alpn]: http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg + * [rfc_2616]: http://www.w3.org/Protocols/rfc2616/rfc2616.html + * [rfc_7540]: https://tools.ietf.org/html/rfc7540 + * [rfc_7540_34]: https://tools.ietf.org/html/rfc7540#section-3.4 + * * @param protocols the protocols to use, in order of preference. If the list contains * [Protocol.H2_PRIOR_KNOWLEDGE] then that must be the only protocol and HTTPS URLs will not * be supported. Otherwise the list must contain [Protocol.HTTP_1_1]. The list must diff --git a/okhttp/src/main/java/okhttp3/Protocol.kt b/okhttp/src/main/java/okhttp3/Protocol.kt index a38b8411c..d3f920362 100644 --- a/okhttp/src/main/java/okhttp3/Protocol.kt +++ b/okhttp/src/main/java/okhttp3/Protocol.kt @@ -18,15 +18,15 @@ package okhttp3 import java.io.IOException /** - * Protocols that OkHttp implements for - * [ALPN](http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg) selection. + * Protocols that OkHttp implements for [ALPN][ietf_alpn] selection. * - * Protocol vs Scheme - * ------------------ + * ## Protocol vs Scheme * * Despite its name, [java.net.URL.getProtocol] returns the [scheme][java.net.URI.getScheme] (http, * https, etc.) of the URL, not the protocol (http/1.1, spdy/3.1, etc.). OkHttp uses the word * *protocol* to identify how HTTP messages are framed. + * + * [ietf_alpn]: http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg */ enum class Protocol(private val protocol: String) { /** @@ -37,8 +37,9 @@ enum class Protocol(private val protocol: String) { /** * A plaintext framing that includes persistent connections. * - * This version of OkHttp implements [RFC 7230](https://tools.ietf.org/html/rfc7230), and tracks - * revisions to that spec. + * This version of OkHttp implements [RFC 7230][rfc_7230], and tracks revisions to that spec. + * + * [rfc_7230]: https://tools.ietf.org/html/rfc7230 */ HTTP_1_1("http/1.1"), @@ -66,7 +67,9 @@ enum class Protocol(private val protocol: String) { * Cleartext HTTP/2 with no "upgrade" round trip. This option requires the client to have prior * knowledge that the server supports cleartext HTTP/2. * - * @see [Starting HTTP/2 with Prior Knowledge](https://tools.ietf.org/html/rfc7540.section-3.4) + * See also [Starting HTTP/2 with Prior Knowledge][rfc_7540_34]. + * + * [rfc_7540_34]: https://tools.ietf.org/html/rfc7540.section-3.4 */ H2_PRIOR_KNOWLEDGE("h2_prior_knowledge"), @@ -84,7 +87,9 @@ enum class Protocol(private val protocol: String) { * Returns the string used to identify this protocol for ALPN, like "http/1.1", "spdy/3.1" or * "h2". * - * @see [IANA tls-extensiontype-values](https://www.iana.org/assignments/tls-extensiontype-values) + * See also [IANA tls-extensiontype-values][iana]. + * + * [iana]: https://www.iana.org/assignments/tls-extensiontype-values */ override fun toString() = protocol diff --git a/okhttp/src/main/java/okhttp3/Route.kt b/okhttp/src/main/java/okhttp3/Route.kt index 36e86650f..d6a29e5cd 100644 --- a/okhttp/src/main/java/okhttp3/Route.kt +++ b/okhttp/src/main/java/okhttp3/Route.kt @@ -51,7 +51,9 @@ class Route( /** * Returns true if this route tunnels HTTPS through an HTTP proxy. - * See [RFC 2817, Section 5.2](http://www.ietf.org/rfc/rfc2817.txt). + * See [RFC 2817, Section 5.2][rfc_2817]. + * + * [rfc_2817]: http://www.ietf.org/rfc/rfc2817.txt */ fun requiresTunnel(): Boolean { return address.sslSocketFactory() != null && proxy.type() == Proxy.Type.HTTP diff --git a/okhttp/src/main/java/okhttp3/WebSocket.kt b/okhttp/src/main/java/okhttp3/WebSocket.kt index e0d74e99d..fa3524e90 100644 --- a/okhttp/src/main/java/okhttp3/WebSocket.kt +++ b/okhttp/src/main/java/okhttp3/WebSocket.kt @@ -21,8 +21,7 @@ import okio.ByteString * A non-blocking interface to a web socket. Use the [factory][WebSocket.Factory] to create * instances; usually this is [OkHttpClient]. * - * Web Socket Lifecycle - * -------------------- + * ## Web Socket Lifecycle * * Upon normal operation each web socket progresses through a sequence of states: * @@ -96,8 +95,8 @@ interface WebSocket { * This returns true if a graceful shutdown was initiated by this call. It returns false if * a graceful shutdown was already underway or if the web socket is already closed or canceled. * - * @param code Status code as defined by [Section 7.4 of RFC - * 6455](http://tools.ietf.org/html/rfc6455#section-7.4). + * @param code Status code as defined by + * [Section 7.4 of RFC 6455](http://tools.ietf.org/html/rfc6455#section-7.4). * @param reason Reason for shutting down or null. * @throws IllegalArgumentException if code is invalid. */