diff --git a/packages/verified-fetch/README.md b/packages/verified-fetch/README.md
index e0c0535f6..036ee2789 100644
--- a/packages/verified-fetch/README.md
+++ b/packages/verified-fetch/README.md
@@ -45,7 +45,7 @@ const json = await resp.json()
 import { verifiedFetch } from '@helia/verified-fetch'
 import { CID } from 'multiformats/cid'
 
-const cid = CID.parse('bafyFoo') // some image file
+const cid = CID.parse('bafyFoo') // some json file
 const response = await verifiedFetch(cid)
 const json = await response.json()
 ```
diff --git a/packages/verified-fetch/src/index.ts b/packages/verified-fetch/src/index.ts
index 66ec8b791..3fd0e6342 100644
--- a/packages/verified-fetch/src/index.ts
+++ b/packages/verified-fetch/src/index.ts
@@ -3,7 +3,7 @@
  *
  * `@helia/verified-fetch` provides a [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-like API for retrieving content from the [IPFS](https://ipfs.tech/) network.
  *
- * All content is retrieved in a [trustless manner](https://www.techopedia.com/definition/trustless), and the integrity of all bytes are verified by comparing hashes of the data.
+ * All content is retrieved in a [trustless manner](https://www.techopedia.com/definition/trustless), and the integrity of all bytes are verified by comparing hashes of the data. By default, CIDs are retrieved over HTTP from [trustless gateways](https://specs.ipfs.tech/http-gateways/trustless-gateway/).
  *
  * This is a marked improvement over `fetch` which offers no such protections and is vulnerable to all sorts of attacks like [Content Spoofing](https://owasp.org/www-community/attacks/Content_Spoofing), [DNS Hijacking](https://en.wikipedia.org/wiki/DNS_hijacking), etc.
  *
@@ -33,7 +33,7 @@
  * import { verifiedFetch } from '@helia/verified-fetch'
  * import { CID } from 'multiformats/cid'
  *
- * const cid = CID.parse('bafyFoo') // some image file
+ * const cid = CID.parse('bafyFoo') // some json file
  * const response = await verifiedFetch(cid)
  * const json = await response.json()
  * ```
@@ -140,7 +140,7 @@
  *
  * ### IPLD codec handling
  *
- * IPFS supports several data formats and `@helia/verified-fetch` attempts to abstract away some of the details.
+ * IPFS supports several data formats (typically referred to as codecs) which are included in the CID. `@helia/verified-fetch` attempts to abstract away some of the details for easier consumption.
  *
  * #### DAG-PB
  *
@@ -148,7 +148,7 @@
  *
  * ##### Using the DAG-PB codec as a Blob
  *
- * ```TypeScript
+ * ```typescript
  * import { verifiedFetch } from '@helia/verified-fetch'
  *
  * const res = await verifiedFetch('ipfs://Qmfoo')
@@ -159,7 +159,7 @@
  *
  * ##### Using the DAG-PB codec as an ArrayBuffer
  *
- * ```TypeScript
+ * ```typescript
  * import { verifiedFetch } from '@helia/verified-fetch'
  *
  * const res = await verifiedFetch('ipfs://Qmfoo')
@@ -170,7 +170,7 @@
  *
  * ##### Using the DAG-PB codec as a stream
  *
- * ```TypeScript
+ * ```typescript
  * import { verifiedFetch } from '@helia/verified-fetch'
  *
  * const res = await verifiedFetch('ipfs://Qmfoo')
@@ -199,7 +199,7 @@
  *
  * ##### Using the JSON codec
  *
- * ```TypeScript
+ * ```typescript
  * import * as json from 'multiformats/codecs/json'
  *
  * const block = new TextEncoder().encode('{ "hello": "world" }')
@@ -227,7 +227,7 @@
  *
  * ##### Using the DAG-JSON codec
  *
- * ```TypeScript
+ * ```typescript
  * import * as dagJson from '@ipld/dag-json'
  *
  * const block = new TextEncoder().encode(`{
@@ -254,11 +254,11 @@
  *
  * ##### Content-Type
  *
- * When the `DAG-JSON` codec is encountered, the `Content-Type` header of the response will be set to `application/json`.
+ * When the `DAG-JSON` codec is encountered in the requested CID, the `Content-Type` header of the response will be set to `application/json`.
  *
  * `DAG-JSON` data can be parsed from the response by using the `.json()` function, which will return `CID`s/byte arrays as plain `{ "/": ... }` objects:
  *
- * ```TypeScript
+ * ```typescript
  * import { verifiedFetch } from '@helia/verified-fetch'
  * import * as dagJson from '@ipld/dag-json'
  *
@@ -270,9 +270,9 @@
  * console.info(obj.buf) // { "/": { "bytes": "AAECAwQ" } }
  * ```
  *
- * Alternatively or it can be decoded using the `@ipld/dag-json` module and the `.arrayBuffer()` method, in which case you will get `CID` objects and `Uint8Array`s:
+ * Alternatively, it can be decoded using the `@ipld/dag-json` module and the `.arrayBuffer()` method, in which case you will get `CID` objects and `Uint8Array`s:
  *
- *```TypeScript
+ *```typescript
  * import { verifiedFetch } from '@helia/verified-fetch'
  * import * as dagJson from '@ipld/dag-json'
  *
@@ -292,7 +292,7 @@
  *
  * ##### Content-Type
  *
- * Not all data types supported by `DAG-CBOR` can be successfully turned into JSON and back.
+ * Not all data types supported by `DAG-CBOR` can be successfully turned into JSON and back into the same binary form.
  *
  * When a decoded block can be round-tripped to JSON, the `Content-Type` will be set to `application/json`. In this case the `.json()` method on the `Response` object can be used to obtain an object representation of the response.
  *
@@ -302,7 +302,7 @@
  *
  * If the `Content-Type` header of the response is `application/json`, the `.json()` method may be used to access the response body in object form, otherwise the `.arrayBuffer()` method must be used to decode the raw bytes using the `@ipld/dag-cbor` module.
  *
- * ```TypeScript
+ * ```typescript
  * import { verifiedFetch } from '@helia/verified-fetch'
  * import * as dagCbor from '@ipld/dag-cbor'
  *
@@ -337,7 +337,7 @@
  * 2. IPNS protocol: `ipns://<peerId>` & `ipns://<publicKey>` & `ipns://<hostUri_Supporting_DnsLink_TxtRecords>`
  * 3. CID instances: An actual CID instance `CID.parse('bafy...')`
  *
- * As well as support for pathing & params for item 1 & 2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
+ * As well as support for pathing & params for items 1 & 2 above according to [IPFS - Path Gateway Specification](https://specs.ipfs.tech/http-gateways/path-gateway) & [IPFS - Trustless Gateway Specification](https://specs.ipfs.tech/http-gateways/trustless-gateway/). Further refinement of those specifications specifically for web-based scenarios can be found in the [Web Pathing Specification IPIP](https://github.com/ipfs/specs/pull/453).
  *
  * If you pass a CID instance, it assumes you want the content for that specific CID only, and does not support pathing or params for that CID.
  *