doc: improve some docs

Author: ChALkeR

README.md

@@ -120,6 +120,13 @@ Encode a string to UTF-8 bytes (strict mode)
 
 Throws on invalid Unicode (unpaired surrogates)
 
+This is similar to the following snippet (but works on all engines):
+```js
+// Strict encode, requiring Unicode codepoints to be valid
+if (typeof string !== 'string' || !string.isWellFormed()) throw new TypeError()
+return new TextEncoder().encode(string)
+```
+
 #### `utf8fromStringLoose(string, format = 'uint8')`
 
 Encode a string to UTF-8 bytes (loose mode)
@@ -130,12 +137,22 @@ per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
 _Such replacement is a non-injective function, is irreversable and causes collisions.\
 Prefer using strict throwing methods for cryptography applications._
 
+This is similar to the following snippet (but works on all engines):
+```js
+// Loose encode, replacing invalid Unicode codepoints with U+FFFD
+if (typeof string !== 'string') throw new TypeError()
+return new TextEncoder().encode(string)
+```
+
 #### `utf8toString(arr)`
 
 Decode UTF-8 bytes to a string (strict mode)
 
 Throws on invalid UTF-8 byte sequences
 
+This is similar to `new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(arr)`,
+but works on all engines.
+
 #### `utf8toStringLoose(arr)`
 
 Decode UTF-8 bytes to a string (loose mode)
@@ -146,6 +163,9 @@ per [WHATWG Encoding](https://encoding.spec.whatwg.org/) specification.
 _Such replacement is a non-injective function, is irreversable and causes collisions.\
 Prefer using strict throwing methods for cryptography applications._
 
+This is similar to `new TextDecoder('utf-8', { ignoreBOM: true }).decode(arr)`,
+but works on all engines.
+
 ### `@exodus/bytes/utf16.js`
 
 UTF-16 encoding/decoding
@@ -271,8 +291,9 @@ Same as:
 const latin1toString = createSinglebyteDecoder('iso-8859-1')
 ```
 
-Note: this is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as
-those alias to `new TextDecoder('windows-1252')`.
+> [!NOTE]
+> This is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as those
+> alias to `new TextDecoder('windows-1252')`.
 
 #### `latin1fromString(string)`
 
@@ -610,7 +631,8 @@ import { typedView } from '@exodus/bytes/array.js'
 
 Create a view of a TypedArray in the specified format (`'uint8'` or `'buffer'`)
 
-Important: does not copy data, returns a view on the same underlying buffer
+> [!IMPORTANT]
+> Does not copy data, returns a view on the same underlying buffer
 
 ### `@exodus/bytes/encoding.js`
 

array.d.ts

@@ -50,7 +50,8 @@ export type OutputFormat = 'uint8' | 'buffer';
 /**
  * Create a view of a TypedArray in the specified format (`'uint8'` or `'buffer'`)
  *
- * Important: does not copy data, returns a view on the same underlying buffer
+ * > [!IMPORTANT]
+ * > Does not copy data, returns a view on the same underlying buffer
  *
  * @param arr - The input TypedArray
  * @param format - The desired output format (`'uint8'` or `'buffer'`)

single-byte.d.ts

@@ -95,8 +95,9 @@ export function createSinglebyteEncoder(
  * const latin1toString = createSinglebyteDecoder('iso-8859-1')
  * ```
  *
- * Note: this is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as
- * those alias to `new TextDecoder('windows-1252')`.
+ * > [!NOTE]
+ * > This is different from `new TextDecoder('iso-8859-1')` and `new TextDecoder('latin1')`, as those
+ * > alias to `new TextDecoder('windows-1252')`.
  *
  * @param arr - The bytes to decode
  * @returns The decoded string

utf8.d.ts

@@ -23,6 +23,13 @@ import type { OutputFormat, Uint8ArrayBuffer } from './array.js';
  *
  * Throws on invalid Unicode (unpaired surrogates)
  *
+ * This is similar to the following snippet (but works on all engines):
+ * ```js
+ * // Strict encode, requiring Unicode codepoints to be valid
+ * if (typeof string !== 'string' || !string.isWellFormed()) throw new TypeError()
+ * return new TextEncoder().encode(string)
+ * ```
+ *
  * @param string - The string to encode
  * @param format - Output format (default: 'uint8')
  * @returns The encoded bytes
@@ -40,6 +47,13 @@ export function utf8fromString(string: string, format?: OutputFormat): Uint8Arra
  * _Such replacement is a non-injective function, is irreversable and causes collisions.\
  * Prefer using strict throwing methods for cryptography applications._
  *
+ * This is similar to the following snippet (but works on all engines):
+ * ```js
+ * // Loose encode, replacing invalid Unicode codepoints with U+FFFD
+ * if (typeof string !== 'string') throw new TypeError()
+ * return new TextEncoder().encode(string)
+ * ```
+ *
  * @param string - The string to encode
  * @param format - Output format (default: 'uint8')
  * @returns The encoded bytes
@@ -56,6 +70,9 @@ export function utf8fromStringLoose(
  *
  * Throws on invalid UTF-8 byte sequences
  *
+ * This is similar to `new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(arr)`,
+ * but works on all engines.
+ *
  * @param arr - The bytes to decode
  * @returns The decoded string
  */
@@ -70,6 +87,9 @@ export function utf8toString(arr: Uint8Array): string;
  * _Such replacement is a non-injective function, is irreversable and causes collisions.\
  * Prefer using strict throwing methods for cryptography applications._
  *
+ * This is similar to `new TextDecoder('utf-8', { ignoreBOM: true }).decode(arr)`,
+ * but works on all engines.
+ *
  * @param arr - The bytes to decode
  * @returns The decoded string
  */