Minor docs improvements

Author: sindresorhus

documentation/1-promise.md

@@ -11,7 +11,7 @@ Although in order to support cancelation, [`PCancelable`](https://github.com/sin
 
 **Returns: <code>Promise<[Response](response.md)>**</code>
 
-The most common way is to pass the `URL` as the first argument, then the options as the second.
+The most common way is to pass the URL as the first argument, then the options as the second.
 
 ```js
 import got from 'got';
@@ -30,7 +30,7 @@ const {headers} = await got(
 
 **Returns: <code>Promise<[Response](3-streams.md#response-1)>**</code>
 
-Eventually, you can pass only options containing a `url` property.
+Alternatively, you can pass only options containing a `url` property.
 
 ```js
 import got from 'got';

documentation/10-instances.md

@@ -20,7 +20,7 @@ The options used for this instance.
 (options: Options, next: …) => next(options)
 ```
 
-An array of handlers. The `next` funtion returns a [`Promise`](1-promise.md) or a [`Request` Got stream](3-streams.md).
+An array of handlers. The `next` function returns a [`Promise`](1-promise.md) or a [`Request` Got stream](3-streams.md).
 
 You execute them directly by calling `got(…)`. They are some sort of "global hooks" - these functions are called first. The last handler (it's invisible) is either `asPromise` or `asStream`, depending on the `options.isStream` property.
 
@@ -29,7 +29,7 @@ You execute them directly by calling `got(…)`. They are some sort of "global h
 **Type: `boolean`**\
 **Default: `false`**
 
-Determines if `got.defaults.options` can be modified.
+Determines whether `got.defaults.options` can be modified.
 
 ### `got.extend(…options, …instances)`
 
@@ -70,21 +70,21 @@ console.log(headers2['x-lorem']); //=> 'impsum'
 **Note:**
 > - Handlers can be asynchronous and can return a `Promise`, but never a `Promise<Stream>`.
 > - Streams must always be handled synchronously.
-> - In order to perform async work using streams, `beforeRequest` hook should be used instead.
+> - In order to perform async work using streams, the `beforeRequest` hook should be used instead.
 
 The recommended approach for creating handlers that can handle both promises and streams is:
 
 ```js
 import got from 'got';
 
-// Create a non-async handler, but we can return a Promise later
+// Create a non-async handler, but we can return a Promise later.
 const handler = (options, next) => {
 	if (options.isStream) {
 		// It's a Stream, return synchronously.
 		return next(options);
 	}
 
-	// For asynchronous work return a Promise
+	// For asynchronous work, return a Promise.
 	return (async () => {
 		try {
 			const response = await next(options);

documentation/2-options.md

@@ -10,7 +10,7 @@ It is made of getters and setters that provide fast option normalization and val
 #### Merge behavior explained
 
 When an option is already set, setting it again replaces it with a deep clone by default.\
-Otherwise the merge behavior is documented in the correspoding section for the option.
+Otherwise the merge behavior is documented in the corresponding section for the option.
 
 #### How to store options
 
@@ -60,7 +60,7 @@ In the second example, it would throw only when the promise is being executed.
 For TypeScript users, `got` exports a dedicated type called `OptionsInit`.\
 It is a plain object that can store the same properties as `Options`.
 
-Performance-wise there is no difference which one is used, although the construtor may be prefferred as it automatically validates the data.\
+Performance-wise there is no difference which one is used, although the constructor may be preferred as it automatically validates the data.\
 The `Options` approach may give a slight boost as it only clones the options, there is no normalization going on.\
 It is also useful for storing the base configuration of a custom Got client.
 
@@ -585,7 +585,7 @@ See [ToughCookie API](https://github.com/salesforce/tough-cookie#getcookiestring
 **Default: `false`**
 
 Ignore invalid cookies instead of throwing an error.\
-Only useful when the cookieJar option has been set.
+Only useful when the `cookieJar` option has been set.
 
 #### **Note:**
 > - This is not recommended! Use at your own risk.
@@ -599,7 +599,7 @@ Defines if redirect responses should be followed automatically.
 
 #### **Note:**
 > - If a `303` is sent by the server in response to any request type (POST, DELETE, etc.), Got will automatically request the resource pointed to in the location header via GET.\
->  This is in accordance with [the spec](https://tools.ietf.org/html/rfc7231#section-6.4.4).
+>  This is in accordance with the [specification](https://tools.ietf.org/html/rfc7231#section-6.4.4).
 
 ```js
 import got from 'got';
@@ -673,7 +673,7 @@ Useful when making lots of requests to different public hostnames.
 **Type: `4 | 6`**\
 **Default: `undefined`**
 
-The IP version to use. Choosing `undefined` will use the default configuration.
+The IP version to use. Specifying `undefined` will use the default configuration.
 
 ### `request`
 

documentation/4-pagination.md

@@ -105,9 +105,9 @@ This is where you should do the parsing.
 
 The function takes an object with the following properties:
 
-- `response` - the current response object,
-- `currentItems` - items from the current response,
-- `allItems` - an empty array, unless `stackAllItems` is `true`, otherwise it contains all emitted items.
+- `response` - The current response object,
+- `currentItems` - Items from the current response,
+- `allItems` - An empty array, unless `stackAllItems` is `true`, otherwise it contains all emitted items.
 
 It should return an object representing Got options pointing to the next page. If there is no next page, `false` should be returned instead.
 

documentation/5-https.md

@@ -13,9 +13,9 @@ This option represents the options used to make HTTPS requests.
 **Type: `string[]`**\
 **Default: `['http/1.1']`**
 
-Acceptable ALPN protocols.
+Acceptable [ALPN](https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation) protocols.
 
-If the `http2` option is `true`, defaults to `['h2', 'http/1.1']`.
+If the `http2` option is `true`, this defaults to `['h2', 'http/1.1']`.
 
 #### `rejectUnauthorized`
 
@@ -35,7 +35,7 @@ The function must return `undefined` if the check succeeded.\
 If it failed, an `Error` should be returned.
 
 **Note:**
-> - In order to have the function called the certificate must not be expired, self-signed nor with an untrusted-root.
+> - In order to have the function called, the certificate must not be expired, self-signed nor with an untrusted-root.
 
 Check [Node.js docs](https://nodejs.org/api/https.html#https_https_request_url_options_callback) for an example.
 
@@ -46,7 +46,7 @@ Check [Node.js docs](https://nodejs.org/api/https.html#https_https_request_url_o
 **Note:**
 > - The option has been renamed from the [`ca` TLS option](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options) for better readability.
 
-Overrides trusted CA certificates.
+Overrides trusted [CA](https://en.wikipedia.org/wiki/Certificate_authority) certificates.
 
 Defaults to CAs provided by [Mozilla](https://ccadb-public.secure.force.com/mozilla/IncludedCACertificateReport).
 
@@ -115,7 +115,7 @@ Multiple PFX can be be provided as an array of unencrypted buffers or an array o
 
 ### Other HTTPS options
 
-The documentation for the options below is at https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options
+[Documentation for the below options.](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options)
 
 - `ciphers`
 - `dhparam`

documentation/6-timeout.md

@@ -59,7 +59,7 @@ console.log(timings);
 
 **Type: `object`**
 
-This object describes maximum allowed time for particular events.
+This object describes the maximum allowed time for particular events.
 
 #### `lookup`
 

documentation/7-retry.md

@@ -3,7 +3,7 @@
 ## Retry API
 
 **Note:**
-> If you're looking for retry implemenation using streams, check out the [Retry Stream API](3-streams.md#retry).
+> If you're looking for retry implementation using streams, check out the [Retry Stream API](3-streams.md#retry).
 
 **Tip:**
 > You can trigger a retry by throwing the [`RetryError`](8-errors.md#retryerror) in any hook.
@@ -85,13 +85,13 @@ The allowed [HTTP status codes](https://developer.mozilla.org/en-US/docs/Web/HTT
 
 The allowed error codes to retry on.
 
-- `ETIMEDOUT` - one of the [timeout limits](6-timeout.md) was reached.
-- `ECONNRESET`- the connection was forcibly closed.
-- `EADDRINUSE`- could not bind to any free port.
-- `ECONNREFUSED`- the connection was refused by the server.
-- `EPIPE` - the remote side of the stream being written has been closed.
-- `ENOTFOUND` - couldn't resolve the hostname to an IP address.
-- `ENETUNREACH` - no internet connection.
+- `ETIMEDOUT` - One of the [timeout limits](6-timeout.md) was reached.
+- `ECONNRESET`- The connection was forcibly closed.
+- `EADDRINUSE`- Could not bind to any free port.
+- `ECONNREFUSED`- The connection was refused by the server.
+- `EPIPE` - The remote side of the stream being written has been closed.
+- `ENOTFOUND` - Could not resolve the hostname to an IP address.
+- `ENETUNREACH` - No internet connection.
 - `EAI_AGAIN` - DNS lookup timed out.
 
 #### `maxRetryAfter`

documentation/8-errors.md

@@ -9,14 +9,14 @@ Source code:
 
 All Got errors contain various metadata, such as:
 
-- `code` - a string like `ERR_NON_2XX_3XX_RESPONSE`,
-- `options` - an instance of [`Options`](`2-options.md`),
-- `request` - an instance of Got Stream,
-- `response` (optional) - an instance of Got Response,
-- `timings` (optional) - points to `response.timings`.
+- `code` - A string like `ERR_NON_2XX_3XX_RESPONSE`,
+- `options` - An instance of [`Options`](`2-options.md`),
+- `request` - An instance of Got Stream,
+- `response` (optional) - An instance of Got Response,
+- `timings` (optional) - Points to `response.timings`.
 
 **Note:**
-> - The `error.stack` property may look incomplete due the execution in async function that is trigerred by a timer.
+> - The `error.stack` property may look incomplete due to the execution in an async function that is triggered by a timer.
 > - See https://stackoverflow.com/questions/54914770/is-there-a-good-way-to-surface-error-traces-in-production-across-event-emitters
 
 **Note:**

documentation/9-hooks.md

@@ -17,11 +17,11 @@ This option represents the hooks to run.
 (plainRequestOptions: OptionsInit, options: Options) => void
 ```
 
-Called with plain request options, right before their normalization.\
+Called with the plain request options, right before their normalization.\
 The second argument represents the current [`Options`](2-options.md) instance.
 
 **Note:**
-> - This is called every time options get merged.
+> - This is called every time options are merged.
 
 **Note:**
 > - This hook is called when a new instance of `Options` is created.
@@ -32,7 +32,7 @@ The second argument represents the current [`Options`](2-options.md) instance.
 
 This is especially useful in conjunction with `got.extend()` when the input needs custom handling.
 
-For example this can be used to fix typos to migrate from older versions faster.
+For example, this can be used to fix typos to migrate from older versions faster.
 
 ```js
 import got from 'got';
@@ -111,7 +111,7 @@ This hook is especially useful in conjunction with `got.extend()` when you want
 > - Got will make no further changes to the request before it is sent.
 
 **Note:**
-> - Changing `options.json` or `options.form` has no effect on the request, you should change `options.body` instead. If needed, update the `options.headers` accordingly.
+> - Changing `options.json` or `options.form` has no effect on the request. You should change `options.body` instead. If needed, update the `options.headers` accordingly.
 
 ```js
 import got from 'got';
@@ -134,7 +134,7 @@ const resposne = await got.post(
 
 **Tip:**
 > - You can indirectly override the `request` function by early returning a [`ClientRequest`-like](https://nodejs.org/api/http.html#http_class_http_clientrequest) instance or a [`IncomingMessage`-like](https://nodejs.org/api/http.html#http_class_http_incomingmessage) instance. This is very useful when creating a custom cache mechanism.
-> - [Read more about this tip](https://github.com/sindresorhus/got/blob/docs-v12/documentation/cache.md#advanced-caching-mechanisms).
+> - [Read more about this tip](cache.md#advanced-caching-mechanisms).
 
 #### `beforeRedirect`
 
@@ -176,15 +176,15 @@ const response = await got('https://example.com', {
 ```
 
 **Note:**
-> - When using Stream API, this hook is ignored.
+> - When using the Stream API, this hook is ignored.
 
 **Note:**
-> - When retrying, `beforeRequest` hook is called afterwards.
+> - When retrying, the `beforeRequest` hook is called afterwards.
 
 **Note:**
-> - If no retry occurs, `beforeError` is called instead.
+> - If no retry occurs, the `beforeError` hook is called instead.
 
-This hook is especially useful when you want to retrieve the cause of retry.
+This hook is especially useful when you want to retrieve the cause of a retry.
 
 ```js
 import got from 'got';
@@ -211,7 +211,7 @@ await got('https://httpbin.org/status/500', {
 ```
 
 **Note:**
-> - When using Stream API, this hook is ignored.
+> - When using the Stream API, this hook is ignored.
 
 **Note:**
 > - Calling the retry function will trigger `beforeRetry` hooks.

documentation/cache.md

@@ -23,7 +23,6 @@ console.log(response.isFromCache);
 Got uses [Keyv](https://github.com/lukechilds/keyv) internally to support a wide range of storage adapters. For something more scalable you could use an [official Keyv storage adapter](https://github.com/lukechilds/keyv#official-storage-adapters):
 
 ```
-$ yarn add @keyv/redis
 $ npm install @keyv/redis
 ```
 

documentation/lets-make-a-plugin.md

@@ -29,13 +29,13 @@ Let's write down the most important information:
 
 Also `X-GitHub-Request-Id` may be useful for debugging.
 
-8. User-Agent is required.
+8. The `User-Agent` header is required.
 
 When we have all the necessary info, we can start mixing :cake:
 
 ### The root endpoint
 
-Not much to do here, just extend an instance and provide the `prefixUrl` option:
+Not much to do here. Just extend an instance and provide the `prefixUrl` option:
 
 ```js
 import got from 'got';
@@ -206,7 +206,7 @@ The conversion is the last thing here.
 
 ### Rate limiting
 
-Umm... `response.headers['x-ratelimit-remaining']` doesn't look good. What about `response.rateLimit.limit` instead?<br>
+Umm... `response.headers['x-ratelimit-remaining']` doesn't look good. What about `response.rateLimit.limit` instead?\
 Yeah, definitely. Since `response.headers` is an object, we can easily parse these:
 
 ```js

documentation/tips.md

@@ -39,7 +39,7 @@ In order to specify retriable errors, use the [Retry API](7-retry.md).
 
 ### Cookies
 
-Got supports cookies out of box. There is no need for parsing them manually.\
+Got supports cookies out of box. There is no need to parse them manually.\
 In order to use cookies, pass a `CookieJar` instance from the [`tough-cookie`](https://github.com/salesforce/tough-cookie) package.
 
 ```js
@@ -98,8 +98,8 @@ Requests can also be sent via [UNIX Domain Sockets](https://serverfault.com/ques
 Use the following URL scheme: `PROTOCOL://unix:SOCKET:PATH`
 
 - `PROTOCOL` - `http` or `https`
-- `SOCKET` - absolute path to a unix domain socket, for example: `/var/run/docker.sock`
-- `PATH` - request path, for example: `/v2/keys`
+- `SOCKET` - Absolute path to a unix domain socket, for example: `/var/run/docker.sock`
+- `PATH` - Request path, for example: `/v2/keys`
 
 ```js
 import got from 'got';
@@ -115,8 +115,8 @@ await got('unix:/var/run/docker.sock:/containers/json');
 Got uses the native [`http`](https://nodejs.org/api/http.html) module, which depends on the native [`net`](https://nodejs.org/api/net.html) module.\
 This means there are two possible ways to test:
 
-1. use a mocking library like [`nock`](https://github.com/nock/nock),
-2. create a server.
+1. Use a mocking library like [`nock`](https://github.com/nock/nock),
+2. Create a server.
 
 The first approach should cover all common use cases.\
 Bear in mind that it overrides the native `http` module, so bugs may occur due to the differences.

readme.md

@@ -63,7 +63,6 @@ For browser usage, we recommend [Ky](https://github.com/sindresorhus/ky) by the
 ## Install
 
 ```
-$ yarn add got
 $ npm install got
 ```