sha3.h: add @author, @copyright, @brief to file header, add examples for all functions, improve documentation links

1 files changed, 1123 insertions, 470 deletions

diff --git a/sha3.h b/sha3.h
index 6dc7546..589c44f 100644
--- a/sha3.h
+++ b/sha3.h
@@ -1,12 +1,17 @@
 /**
  * @file sha3.h
+ * @author Paul Duncan
+ * @copyright MIT No Attribution (MIT-0)
+ * @brief C11 implementation of FIPS 202, NIST SP 800-185, and the draft KangarooTwelve and TurboSHAKE specification.
+ *
  * sha3
  * https://pablotron.org/sha3
  *
  * Copyright (c) 2023 Paul Duncan
  * SPDX-License-Identifier: MIT-0
  *
- * C11 implementations of the following SHA-3 algorithms:
+ * Embeddable, dependency-free, MIT-0-licensed C11 implementation of the
+ * following SHA-3 hash functions, XOFs, and HMACs:
  *
  * - SHA3-224, SHA3-256, SHA3-384, and SHA3-512
  * - HMAC-SHA3-224, HMAC-SHA3-256, HMAC-SHA3-384, and HMAC-SHA3-512
@@ -18,7 +23,6 @@
  * - TurboSHAKE128 and TurboSHAKE256
  * - KangarooTwelve
  */
-
 #ifndef SHA3_H
 #define SHA3_H
 
@@ -55,8 +59,11 @@ extern "C" {
  */
 
 /**
- * @brief Internal SHA-3 state (all members are private).
+ * @brief Internal [SHA-3][] state (all members are private).
  * @ingroup sha3
+ *
+ * [SHA-3]: https://en.wikipedia.org/wiki/SHA-3
+ *   "Secure Hash Algorithm 3"
  */
 typedef union {
   uint8_t u8[200]; /**< 8-bit unsigned integers. */
@@ -64,8 +71,11 @@ typedef union {
 } sha3_state_t;
 
 /**
- * @brief Iterative SHA-3 context (all members are private).
+ * @brief Iterative [SHA-3][] context (all members are private).
  * @ingroup sha3
+ *
+ * [SHA-3]: https://en.wikipedia.org/wiki/SHA-3
+ *   "Secure Hash Algorithm 3"
  */
 typedef struct {
   size_t num_bytes; /**< number of bytes absorbed */
@@ -74,8 +84,11 @@ typedef struct {
 } sha3_t;
 
 /**
- * @brief Iterative XOF context (all members are private).
+ * @brief Iterative [XOF][] context (all members are private).
  * @ingroup shake
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 typedef struct {
   size_t num_bytes; /**< number of bytes absorbed */
@@ -88,12 +101,18 @@ typedef struct {
  * @ingroup sha3
  *
  * Hash `len` bytes of input data from source buffer `src` with SHA3-224
- * (FIPS 202, section 6.1), then write 28 bytes of output to destination
- * buffer `dst`.
+ * ([FIPS 202][], section 6.1), then write 28 bytes of output to
+ * destination buffer `dst`.
  *
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
- * @param[out] dst Destination array.  Must be at least 28 bytes in length.
+ * @param[out] dst Destination buffer.  Must be at least 28 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_224
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
 void sha3_224(const uint8_t *src, size_t len, uint8_t dst[static 28]);
 
@@ -102,6 +121,9 @@ void sha3_224(const uint8_t *src, size_t len, uint8_t dst[static 28]);
  * @ingroup sha3
  *
  * @param[out] hash SHA3-224 hash context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_224_absorb
  */
 void sha3_224_init(sha3_t *hash);
 
@@ -118,6 +140,9 @@ void sha3_224_init(sha3_t *hash);
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_224_absorb
  */
 _Bool sha3_224_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
 
@@ -128,6 +153,9 @@ _Bool sha3_224_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
  *
  * @param[in,out] hash SHA3-224 hash context.
  * @param[out] dst Destination buffer.  Must be at least 28 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_224_absorb
  */
 void sha3_224_final(sha3_t *hash, uint8_t dst[28]);
 
@@ -136,12 +164,18 @@ void sha3_224_final(sha3_t *hash, uint8_t dst[28]);
  * @ingroup sha3
  *
  * Hash `len` bytes of input data from source buffer `src` with SHA3-256
- * (FIPS 202, section 6.1), then write 32 bytes of output to destination
- * buffer `dst`.
+ * ([FIPS 202][], section 6.1), then write 32 bytes of output to
+ * destination buffer `dst`.
  *
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
- * @param[out] dst Destination array.  Must be at least 32 bytes in length.
+ * @param[out] dst Destination buffer.  Must be at least 32 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_256
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
 void sha3_256(const uint8_t *src, size_t len, uint8_t dst[static 32]);
 
@@ -150,6 +184,9 @@ void sha3_256(const uint8_t *src, size_t len, uint8_t dst[static 32]);
  * @ingroup sha3
  *
  * @param[out] hash SHA3-256 hash context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_256_absorb
  */
 void sha3_256_init(sha3_t *hash);
 
@@ -166,6 +203,9 @@ void sha3_256_init(sha3_t *hash);
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_256_absorb
  */
 _Bool sha3_256_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
 
@@ -176,6 +216,9 @@ _Bool sha3_256_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
  *
  * @param[in,out] hash SHA3-256 hash context.
  * @param[out] dst Destination buffer.  Must be at least 32 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_256_absorb
  */
 void sha3_256_final(sha3_t *hash, uint8_t dst[32]);
 
@@ -184,12 +227,18 @@ void sha3_256_final(sha3_t *hash, uint8_t dst[32]);
  * @ingroup sha3
  *
  * Hash `len` bytes of input data from source buffer `src` with SHA3-384
- * (FIPS 202, section 6.1), then write 48 bytes of output to destination
- * buffer `dst`.
+ * ([FIPS 202][], section 6.1), then write 48 bytes of output to
+ * destination buffer `dst`.
  *
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
- * @param[out] dst Destination array.  Must be at least 48 bytes in length.
+ * @param[out] dst Destination buffer.  Must be at least 48 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_384
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
 void sha3_384(const uint8_t *src, size_t len, uint8_t dst[static 48]);
 
@@ -198,6 +247,9 @@ void sha3_384(const uint8_t *src, size_t len, uint8_t dst[static 48]);
  * @ingroup sha3
  *
  * @param[out] hash SHA3-384 hash context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_384_absorb
  */
 void sha3_384_init(sha3_t *hash);
 
@@ -214,6 +266,9 @@ void sha3_384_init(sha3_t *hash);
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_384_absorb
  */
 _Bool sha3_384_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
 
@@ -224,6 +279,9 @@ _Bool sha3_384_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
  *
  * @param[in,out] hash SHA3-384 hash context.
  * @param[out] dst Destination buffer.  Must be at least 48 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_384_absorb
  */
 void sha3_384_final(sha3_t *hash, uint8_t dst[48]);
 
@@ -232,12 +290,18 @@ void sha3_384_final(sha3_t *hash, uint8_t dst[48]);
  * @ingroup sha3
  *
  * Hash `len` bytes of input data from source buffer `src` with SHA3-512
- * (FIPS 202, section 6.1), then write 64 bytes of output to destination
- * buffer `dst`.
+ * ([FIPS 202][], section 6.1), then write 64 bytes of output to
+ * destination buffer `dst`.
  *
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
- * @param[out] dst Destination array.  Must be at least 64 bytes in length.
+ * @param[out] dst Destination buffer.  Must be at least 64 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_512
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
 void sha3_512(const uint8_t *src, size_t len, uint8_t dst[static 64]);
 
@@ -246,6 +310,9 @@ void sha3_512(const uint8_t *src, size_t len, uint8_t dst[static 64]);
  * @ingroup sha3
  *
  * @param[out] hash SHA3-512 hash context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_512_absorb
  */
 void sha3_512_init(sha3_t *hash);
 
@@ -262,6 +329,9 @@ void sha3_512_init(sha3_t *hash);
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_512_absorb
  */
 _Bool sha3_512_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
 
@@ -272,6 +342,9 @@ _Bool sha3_512_absorb(sha3_t *hash, const uint8_t *src, const size_t len);
  *
  * @param[in,out] hash SHA3-512 hash context.
  * @param[out] dst Destination buffer.  Must be at least 64 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c sha3_512_absorb
  */
 void sha3_512_final(sha3_t *hash, uint8_t dst[64]);
 
@@ -298,69 +371,109 @@ void sha3_512_final(sha3_t *hash, uint8_t dst[64]);
  * @brief Calculat HMAC-SHA3-224 of given key and data.
  * @ingroup hmac
  *
- * Calculate HMAC-SHA3-224 (FIPS 202, Section 7) of key in buffer `k` of
- * length `k_len` and input message in buffer `m` of length `m_len`
- * bytes and write 28 bytes of output to destination buffer `dst`.
+ * Calculate HMAC-SHA3-224 ([FIPS 202][], Section 7) of key in buffer
+ * `key` of length `key_len` and input message in buffer `msg` of length
+ * `msg_len` bytes and write 28 byte [message authentication code
+ * (MAC)][] to destination buffer `mac`.
+ *
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ * @param[in] msg Input message.
+ * @param[in] msg_len Input message length, in bytes.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 28 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224
  *
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
- * @param[in] m Input message.
- * @param[in] m_len Input message length, in bytes.
- * @param[out] dst Destination array.  Must be at least 28 bytes in length.
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_224(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[28]);
+void hmac_sha3_224(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[28]);
 
 /**
  * @brief Calculate HMAC-SHA3-256 given key and data.
  * @ingroup hmac
  *
- * Calculate HMAC-SHA3-256 (FIPS 202, Section 7) of key in buffer `k` of
- * length `k_len` and input message in buffer `m` of length `m_len`
- * bytes and write 32 bytes of output to destination buffer `dst`.
+ * Calculate HMAC-SHA3-256 ([FIPS 202][], Section 7) of key in buffer
+ * `key` of length `key_len` and input message in buffer `msg` of length
+ * `msg_len` bytes and write 32 byte [message authentication code
+ * (MAC)][mac] destination buffer `mac`.
+ *
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ * @param[in] msg Input message.
+ * @param[in] msg_len Input message length, in bytes.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 32 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256
  *
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
- * @param[in] m Input message.
- * @param[in] m_len Input message length, in bytes.
- * @param[out] dst Destination array.  Must be at least 32 bytes in length.
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_256(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[32]);
+void hmac_sha3_256(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[32]);
 
 /**
- * Calculate HMAC-SHA3-384 of given key and data.
+ * @brief Calculate HMAC-SHA3-384 of given key and data.
  * @ingroup hmac
  *
- * Calculate HMAC-SHA3-384 (FIPS 202, Section 7) of key in buffer `k` of
- * length `k_len` and input message in buffer `m` of length `m_len`
- * bytes and write 48 bytes of output to destination buffer `dst`.
+ * Calculate HMAC-SHA3-384 ([FIPS 202][], Section 7) of key in buffer
+ * `key` of length `key_len` and input message in buffer `msg` of length
+ * `msg_len` bytes and write 48 byte [message authentication code
+ * (MAC)][mac] destination buffer `mac`.
+ *
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ * @param[in] msg Input message.
+ * @param[in] msg_len Input message length, in bytes.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 48 bytes in length.
  *
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
- * @param[in] m Input message.
- * @param[in] m_len Input message length, in bytes.
- * @param[out] dst Destination array.  Must be at least 48 bytes in length.
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_384
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_384(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[48]);
+void hmac_sha3_384(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[48]);
 
 /**
  * @brief Calculate HMAC-SHA3-512 of given key and data.
  * @ingroup hmac
  *
- * Calculate HMAC-SHA3-512 (FIPS 202, Section 7) of key in buffer `k` of
- * length `k_len` and input message in buffer `m` of length `m_len`
- * bytes and write 64 bytes of output to destination buffer `dst`.
+ * Calculate HMAC-SHA3-512 ([FIPS 202][], Section 7) of key in buffer
+ * `key` of length `key_len` and input message in buffer `msg` of length
+ * `msg_len` bytes and write 64 byte [message authentication code
+ * (MAC)][mac] destination buffer `mac`.
  *
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
- * @param[in] m Input message.
- * @param[in] m_len Input message length, in bytes.
- * @param[out] dst Destination array.  Must be at least 64 bytes in length.
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ * @param[in] msg Input message.
+ * @param[in] msg_len Input message length, in bytes.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 64 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_512(const uint8_t *k, const size_t k_len, const uint8_t *m, const size_t m_len, uint8_t dst[64]);
+void hmac_sha3_512(const uint8_t *key, const size_t key_len, const uint8_t *msg, const size_t msg_len, uint8_t mac[64]);
 
 /**
- * @brief HMAC-SHA3 (Hash-based Message Authentication Code) context.
+ * @brief HMAC-SHA3 (Hash-based [Message Authentication Code][MAC])
+ * context (all members are private).
  * @ingroup hmac
+ *
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
 typedef struct {
   sha3_t inner, /**< Inner hash context (private) */
@@ -369,14 +482,20 @@ typedef struct {
 } hmac_sha3_t;
 
 /**
- * @brief Initialize HMAC-SHA3-224 (FIPS 202, Section 7) context.
+ * @brief Initialize HMAC-SHA3-224 ([FIPS 202][], Section 7) context.
  * @ingroup hmac
  *
- * @param[out] hmac HMAC-SHA3-224 context.
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
+ * @param[out] ctx HMAC-SHA3-224 context.
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224_absorb
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
-void hmac_sha3_224_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len);
+void hmac_sha3_224_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len);
 
 /**
  * @brief Absorb data into HMAC-SHA3-224 context.
@@ -386,137 +505,192 @@ void hmac_sha3_224_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len)
  * context `hmac`.  Can be called iteratively to absorb input data in
  * chunks.
  *
- * @param[in,out] hmac HMAC-SHA3-224 context.
+ * @param[in,out] ctx HMAC-SHA3-224 context.
  * @param[in] src Input data.
  * @param[in] len Input data length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224_absorb
  */
-_Bool hmac_sha3_224_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len);
+_Bool hmac_sha3_224_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len);
 
 /**
- * @brief Finalize HMAC-SHA3-224 hash context and write 28 bytes of
- * output to destination buffer `dst`.
+ * @brief Finalize HMAC-SHA3-224 context and write 28 byte [MAC][]
+ * to destination buffer.
  * @ingroup hmac
  *
- * @param[in,out] hmac HMAC-SHA3-224 hash context.
- * @param[out] dst Destination buffer.  Must be at least 28 bytes in length.
+ * @param[in,out] ctx HMAC-SHA3-224 context.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 28 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_224_absorb
+ *
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_224_final(hmac_sha3_t *hmac, uint8_t dst[28]);
+void hmac_sha3_224_final(hmac_sha3_t *ctx, uint8_t mac[28]);
 
 /**
- * @brief Initialize HMAC-SHA3-256 (FIPS 202, Section 7) context.
+ * @brief Initialize HMAC-SHA3-256 ([FIPS 202][], Section 7) context.
  * @ingroup hmac
  *
- * @param[out] hmac HMAC-SHA3-256 context.
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
+ * @param[out] ctx HMAC-SHA3-256 context.
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256_absorb
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
-void hmac_sha3_256_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len);
+void hmac_sha3_256_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len);
 
 /**
  * @brief Absorb data into HMAC-SHA3-256 context.
  * @ingroup hmac
  *
  * Absorb input data in `src` of length `len` bytes into HMAC-SHA3-256
- * context `hmac`.  Can be called iteratively to absorb input data in
+ * context `ctx`.  Can be called iteratively to absorb input data in
  * chunks.
  *
- * @param[in,out] hmac HMAC-SHA3-256 context.
+ * @param[in,out] ctx HMAC-SHA3-256 context.
  * @param[in] src Input data.
  * @param[in] len Input data length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256_absorb
  */
-_Bool hmac_sha3_256_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len);
+_Bool hmac_sha3_256_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len);
 
 /**
- * @brief Finalize HMAC-SHA3-256 hash context and write 32 bytes of
- * output to destination buffer `dst`.
+ * @brief Finalize HMAC-SHA3-256 context and write 32 byte [MAC][] to
+ * destination buffer.
  * @ingroup hmac
  *
- * @param[in,out] hmac HMAC-SHA3-256 hash context.
- * @param[out] dst Destination buffer.  Must be at least 32 bytes in length.
+ * @param[in,out] ctx HMAC-SHA3-256 context.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 32 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_256_absorb
+ *
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_256_final(hmac_sha3_t *hmac, uint8_t dst[32]);
+void hmac_sha3_256_final(hmac_sha3_t *ctx, uint8_t mac[32]);
 
 /**
- * @brief Initialize HMAC-SHA3-384 (FIPS 202, Section 7) context.
+ * @brief Initialize HMAC-SHA3-384 ([FIPS 202][], Section 7) context.
  * @ingroup hmac
  *
- * @param[out] hmac HMAC-SHA3-384 context.
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
+ * @param[out] ctx HMAC-SHA3-384 context.
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_384_absorb
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
-void hmac_sha3_384_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len);
+void hmac_sha3_384_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len);
 
 /**
  * @brief Absorb data into HMAC-SHA3-384 context.
  * @ingroup hmac
  *
  * Absorb input data in `src` of length `len` bytes into HMAC-SHA3-384
- * context `hmac`.  Can be called iteratively to absorb input data in
+ * context `ctx`.  Can be called iteratively to absorb input data in
  * chunks.
  *
- * @param[in,out] hmac HMAC-SHA3-384 context.
+ * @param[in,out] ctx HMAC-SHA3-384 context.
  * @param[in] src Input data.
  * @param[in] len Input data length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_384_absorb
  */
-_Bool hmac_sha3_384_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len);
+_Bool hmac_sha3_384_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len);
 
 /**
- * @brief Finalize HMAC-SHA3-384 hash context and write 48 bytes of
- * output to destination buffer `dst`.
+ * @brief Finalize HMAC-SHA3-384 context and write 48 byte [MAC][] to
+ * destination buffer.
  * @ingroup hmac
  *
- * @param[in,out] hmac HMAC-SHA3-384 hash context.
- * @param[out] dst Destination buffer.  Must be at least 48 bytes in length.
+ * @param[in,out] ctx HMAC-SHA3-384 context.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 48 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb
+ *
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_384_final(hmac_sha3_t *hmac, uint8_t dst[48]);
+void hmac_sha3_384_final(hmac_sha3_t *ctx, uint8_t mac[48]);
 
 /**
- * @brief Initialize HMAC-SHA3-512 (FIPS 202, Section 7) context.
+ * @brief Initialize HMAC-SHA3-512 ([FIPS 202][], Section 7) context.
  * @ingroup hmac
  *
- * @param[out] hmac HMAC-SHA3-512 context.
- * @param[in] k Key.
- * @param[in] k_len Key length, in bytes.
+ * @param[out] ctx HMAC-SHA3-512 context.
+ * @param[in] key Key.
+ * @param[in] key_len Key length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
-void hmac_sha3_512_init(hmac_sha3_t *hmac, const uint8_t *k, const size_t k_len);
+void hmac_sha3_512_init(hmac_sha3_t *ctx, const uint8_t *key, const size_t key_len);
 
 /**
  * @brief Absorb data into HMAC-SHA3-512 context.
  * @ingroup hmac
  *
  * Absorb input data in `src` of length `len` bytes into HMAC-SHA3-512
- * context `hmac`.  Can be called iteratively to absorb input data in
+ * context `ctx`.  Can be called iteratively to absorb input data in
  * chunks.
  *
- * @param[in,out] hmac HMAC-SHA3-512 context.
+ * @param[in,out] ctx HMAC-SHA3-512 context.
  * @param[in] src Input data.
  * @param[in] len Input data length, in bytes.
  *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb
+ *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
  */
-_Bool hmac_sha3_512_absorb(hmac_sha3_t *hmac, const uint8_t *src, const size_t len);
+_Bool hmac_sha3_512_absorb(hmac_sha3_t *ctx, const uint8_t *src, const size_t len);
 
 /**
- * @brief Finalize HMAC-SHA3-512 hash context and write 64 bytes of
- * output to destination buffer `dst`.
+ * @brief Finalize HMAC-SHA3-512 context and write 64 byte [MAC][]
+ * to destination buffer.
  * @ingroup hmac
  *
- * @param[in,out] hmac HMAC-SHA3-512 hash context.
- * @param[out] dst Destination buffer.  Must be at least 64 bytes in length.
+ * @param[in,out] ctx HMAC-SHA3-512 hash context.
+ * @param[out] mac [MAC][] destination buffer.  Must be at least 64 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c hmac_sha3_512_absorb
+ *
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code (MAC)"
  */
-void hmac_sha3_512_final(hmac_sha3_t *hmac, uint8_t dst[64]);
+void hmac_sha3_512_final(hmac_sha3_t *ctx, uint8_t mac[64]);
 
 /**
  * @defgroup shake SHAKE
  *
- * @brief [SHA-3][] [XOFs][xof] with both fixed-length output and
- * arbitrary-length output, as defined in section 6.2 of [FIPS 202][].
+ * @brief [SHA-3][] [Extendable-output functions (XOFs)][xof] with
+ * fixed-length and arbitrary-length output, as defined in section 6.2
+ * of [FIPS 202][].
  *
  * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
  *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
@@ -530,141 +704,210 @@ void hmac_sha3_512_final(hmac_sha3_t *hmac, uint8_t dst[64]);
  * @brief Hash data with SHAKE128.
  * @ingroup shake
  *
- * Hash input message in buffer `m` of length `m_len` bytes with
- * SHAKE128 (FIPS 202, section 6.2) and write 16 bytes of output to
+ * Hash input message in buffer `msg` of length `len` bytes with
+ * SHAKE128 ([FIPS 202][], section 6.2) and write 16 bytes of output to
  * destination buffer `dst`.
  *
- * @param[in] m Input message.
- * @param[in] m_len Input message length, in bytes.
- * @param[out] dst Destination array.  Must be at least 16 bytes in length.
+ * @param[in] msg Input message.
+ * @param[in] len Input message length, in bytes.
+ * @param[out] dst Destination buffer.  Must be at least 16 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake128
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
-void shake128(const uint8_t *m, size_t m_len, uint8_t dst[static 16]);
+void shake128(const uint8_t *msg, size_t len, uint8_t dst[static 16]);
 
 /**
  * @brief Hash data with SHAKE256.
  * @ingroup shake
  *
- * Hash input message in buffer `m` of length `m_len` bytes with
- * SHAKE256 (FIPS 202, section 6.2) and write the result to output
- * buffer `dst`.
+ * Hash input message in buffer `msg` of length `len` bytes with
+ * SHAKE256 ([FIPS 202][], section 6.2) and write 32 bytes of output to
+ * destination buffer `dst`.
  *
- * @param[in] m Input message.
- * @param[in] m_len Input message length, in bytes.
- * @param[out] dst Destination array.  Must be at least 16 bytes in length.
+ * @param[in] msg Input message.
+ * @param[in] len Input message length, in bytes.
+ * @param[out] dst Destination buffer.  Must be at least 32 bytes in length.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake256
+ *
+ * [FIPS 202]: https://csrc.nist.gov/pubs/fips/202/final
+ *   "SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions"
  */
-void shake256(const uint8_t *m, size_t m_len, uint8_t dst[static 32]);
+void shake256(const uint8_t *msg, size_t len, uint8_t dst[static 32]);
 
 /**
- * @brief Initialize SHAKE128 extendable-output function (XOF) context.
+ * @brief Initialize SHAKE128 [extendable-output function (XOF)][xof] context.
  * @ingroup shake
  *
- * @param[out] xof SHAKE128 XOF context.
+ * @param[out] xof SHAKE128 [XOF][] context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void shake128_xof_init(sha3_xof_t * const xof);
 
 /**
- * @brief Absorb data into SHAKE128 XOF context.
+ * @brief Absorb data into SHAKE128 [XOF][] context.
  * @ingroup shake
  *
- * Absorb input data in `m` of length `len` bytes into SHAKE128 XOF
- * context `xof`.  Can be called iteratively to absorb input data in
- * chunks.
+ * Absorb input data in `msg` of length `len` bytes into SHAKE128
+ * [XOF][] context `xof`.  Can be called iteratively to absorb input
+ * data in chunks.
  *
- * @param[in,out] xof SHAKE128 XOF context.
- * @param[in] m Input data.
+ * @param[in,out] xof SHAKE128 [XOF][] context.
+ * @param[in] msg Input data.
  * @param[in] len Input data length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
-_Bool shake128_xof_absorb(sha3_xof_t *xof, const uint8_t *m, const size_t len);
+_Bool shake128_xof_absorb(sha3_xof_t *xof, const uint8_t *msg, const size_t len);
 
 /**
- * @brief Squeeze bytes from SHAKE128 XOF context.
+ * @brief Squeeze bytes from SHAKE128 [XOF][] context.
  * @ingroup shake
  *
- * Squeeze `dst_len` bytes of output into destination buffer `dst` from
+ * Squeeze `len` bytes of output into destination buffer `dst` from
  * SHAKE128 XOF context `xof`.  Can be called iteratively to squeeze
  * output data in chunks.
  *
- * @param[in,out] xof SHAKE128 XOF context.
+ * @param[in,out] xof SHAKE128 [XOF][] context.
  * @param[out] dst Destination buffer.
- * @param[in] dst_len Destination buffer length, in bytes.
+ * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
-void shake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t dst_len);
+void shake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb data into SHAKE128 XOF, then squeeze bytes out.
+ * @brief Absorb data into SHAKE128 [XOF][], then squeeze bytes out.
  * @ingroup shake
  *
  * Absorb data in buffer `src` of length `src_len` bytes into SHAKE128
- * XOF context, then squeeze `dst_len` bytes of output into destination
- * buffer `dst`.
+ * [XOF][] context, then squeeze `dst_len` bytes of output into
+ * destination buffer `dst`.
+ *
+ * @note This function will produce different output than shake128(),
+ * because shake128() produces fixed-length output and this function
+ * produces arbitrary-length output.
  *
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake128_xof_once
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void shake128_xof_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Initialize SHAKE256 extendable-output function (XOF) context.
+ * @brief Initialize SHAKE256 [extendable-output function (XOF)][xof]
+ * context.
  * @ingroup shake
  *
- * @param[out] xof SHAKE256 XOF context.
+ * @param[out] xof SHAKE256 [XOF][] context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void shake256_xof_init(sha3_xof_t *xof);
 
 /**
- * @brief Absorb data into SHAKE256 XOF context.
+ * @brief Absorb data into SHAKE256 [XOF][] context.
  * @ingroup shake
  *
- * Absorb input data in `m` of length `len` bytes into SHAKE256 XOF
- * context `xof`.  Can be called iteratively to absorb input data in
- * chunks.
+ * Absorb input data in `msg` of length `len` bytes into SHAKE256
+ * [XOF][] context `xof`.  Can be called iteratively to absorb input
+ * data in chunks.
  *
- * @param[in,out] xof SHAKE256 XOF context.
- * @param[in] m Input data.
+ * @param[in,out] xof SHAKE256 [XOF][] context.
+ * @param[in] msg Input data.
  * @param[in] len Input data length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
-_Bool shake256_xof_absorb(sha3_xof_t *xof, const uint8_t *m, const size_t len);
+_Bool shake256_xof_absorb(sha3_xof_t *xof, const uint8_t *msg, const size_t len);
 
 /**
- * @brief Squeeze bytes from SHAKE256 XOF context.
+ * @brief Squeeze bytes from SHAKE256 [XOF][] context.
  * @ingroup shake
  *
- * Squeeze `dst_len` bytes of output into destination buffer `dst` from
- * SHAKE256 XOF context `xof`.  Can be called iteratively to squeeze
+ * Squeeze `len` bytes of output into destination buffer `dst` from
+ * SHAKE256 [XOF][] context `xof`.  Can be called iteratively to squeeze
  * output data in chunks.
  *
- * @param[in,out] xof SHAKE256 XOF context.
+ * @param[in,out] xof SHAKE256 [XOF][] context.
  * @param[out] dst Destination buffer.
- * @param[in] dst_len Destination buffer length, in bytes.
+ * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
-void shake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t dst_len);
+void shake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb data into SHAKE256 XOF, then squeeze bytes out.
+ * @brief Absorb data into SHAKE256 [XOF][], then squeeze bytes out.
  * @ingroup shake
  *
  * Absorb data in buffer `src` of length `src_len` bytes into SHAKE256
- * XOF context, then squeeze `dst_len` bytes of output into destination
- * buffer `dst`.
+ * [XOF][] context, then squeeze `dst_len` bytes of output into
+ * destination buffer `dst`.
+ *
+ * @note This function will produce different output than shake256(),
+ * because shake256() produces fixed-length output and this function
+ * produces arbitrary-length output.
  *
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c shake256_xof_once
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void shake256_xof_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
  * @defgroup cshake cSHAKE
  *
- * @brief Fixed-length and [XOF][] variants of the customizable-SHAKE
- * primitive, as defined in section 3 of [SP 800-185][800-185].
+ * @brief Customizable SHAKE (cSHAKE) [extendable-output function
+ * (XOF)][xof], as defined in section 3 of [SP 800-185][800-185].
  *
  * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
  *   "Extendable-Output Function (XOF)"
@@ -688,20 +931,28 @@ typedef struct {
  * @ingroup cshake
  *
  * Initialize internal cSHAKE128 (customizable SHAKE128, as defined in
- * section 3 of NIST SP 800-185) context with customization parameters
- * `params`, absorb data in buffer `src` of length `src_len` bytes into
- * internal context, then squeeze `dst_len` bytes of output into
- * destination buffer `dst`.
+ * section 3 of [NIST SP 800-185][800-185]) context with customization
+ * parameters `params`, absorb data in buffer `src` of length `src_len`
+ * bytes into internal context, then squeeze `dst_len` bytes of output
+ * into destination buffer `dst`.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the [extendable output functions
+ * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should
+ * generally not be used directly.
  *
  * @param[in] params cSHAKE customization parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake128
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 void cshake128(const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
@@ -710,130 +961,188 @@ void cshake128(const cshake_params_t params, const uint8_t *src, const size_t sr
  * @ingroup cshake
  *
  * Initialize internal cSHAKE256 (customizable SHAKE256, as defined in
- * section 3 of NIST SP 800-185) context with customization parameters
- * `params`, absorb data in buffer `src` of length `src_len` bytes into
- * internal context, then squeeze `dst_len` bytes of output into
- * destination buffer `dst`.
+ * section 3 of [NIST SP 800-185][800-185]) context with customization
+ * parameters `params`, absorb data in buffer `src` of length `src_len`
+ * bytes into internal context, then squeeze `dst_len` bytes of output
+ * into destination buffer `dst`.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the [extendable output functions
+ * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should
+ * generally not be used directly.
  *
  * @param[in] params cSHAKE customization parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake256
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 void cshake256(const cshake_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Initialize cSHAKE128 XOF context.
+ * @brief Initialize cSHAKE128 [XOF][] context.
  * @ingroup cshake
  *
  * Initialize cSHAKE128 (customizable SHAKE128, as defined in section 3 of
- * NIST SP 800-185) XOF context with customization parameters `params`.
+ * [NIST SP 800-185][800-185]) [XOF][] context with customization
+ * parameters `params`.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the [extendable output functions
+ * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should
+ * generally not be used directly.
  *
- * @param[out] xof cSHAKE128 context.
+ * @param[out] xof cSHAKE128 [XOF][] context.
  * @param[in] params cSHAKE128 customization parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 void cshake128_xof_init(sha3_xof_t *xof, const cshake_params_t params);
 
 /**
- * @brief Absorb data into cSHAKE128 XOF context.
+ * @brief Absorb data into cSHAKE128 [XOF][] context.
  * @ingroup cshake
  *
- * Absorb data in buffer `src` of length `len` bytes into cSHAKE128 XOF
- * context `xof`.  Can be called iteratively to absorb input data in
- * chunks.
+ * Absorb data in buffer `src` of length `len` bytes into cSHAKE128
+ * [XOF][] context `xof`.  Can be called iteratively to absorb input
+ * data in chunks.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the [extendable output functions
+ * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should
+ * generally not be used directly.
  *
- * @param[in,out] xof cSHAKE128 context.
+ * @param[in,out] xof cSHAKE128 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 _Bool cshake128_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze bytes from cSHAKE128 XOF context.
+ * @brief Squeeze bytes from cSHAKE128 [XOF][] context.
  * @ingroup cshake
  *
  * Squeeze `dst_len` bytes of output into destination buffer `dst` from
- * cSHAKE128 XOF context `xof`.  Can be called iteratively to squeeze
- * output data in chunks.
+ * cSHAKE128 [XOF][] context `xof`.  Can be called iteratively to
+ * squeeze output data in chunks.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the [extendable output functions
+ * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should
+ * generally not be used directly.
  *
- * @param[in,out] xof cSHAKE128 context.
+ * @param[in,out] xof cSHAKE128 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 void cshake128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Initialize cSHAKE256 XOF context.
+ * @brief Initialize cSHAKE256 [XOF][] context.
  * @ingroup cshake
  *
- * Initialize cSHAKE256 (customizable SHAKE256, as defined in section 3 of
- * NIST SP 800-185) XOF context with customization parameters `params`.
+ * Initialize cSHAKE256 (customizable SHAKE256, as defined in section 3
+ * of [NIST SP 800-185][800-185]) [XOF][] context with customization
+ * parameters `params`.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the [extendable output functions
+ * (XOFs)][xof] defined in [NIST SP 800-185][800-185] and should
+ * generally not be used directly.
  *
  * @ingroup cshake
  *
- * @param[out] xof cSHAKE256 context.
+ * @param[out] xof cSHAKE256 [XOF][] context.
  * @param[in] params cSHAKE256 customization parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 void cshake256_xof_init(sha3_xof_t *xof, const cshake_params_t params);
 
 /**
- * @brief Absorb data into cSHAKE256 XOF context.
+ * @brief Absorb data into cSHAKE256 [XOF][] context.
  * @ingroup cshake
  *
- * Absorb data in buffer `src` of length `len` bytes into cSHAKE256 XOF
- * context `xof`.  Can be called iteratively to absorb input data in
- * chunks.
+ * Absorb data in buffer `src` of length `len` bytes into cSHAKE256
+ * [XOF][] context `xof`.  Can be called iteratively to absorb input
+ * data in chunks.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the hash and [extendable output
+ * functions (XOFs)][xof] defined in [NIST SP 800-185][800-185] and
+ * should generally not be used directly.
  *
- * @param[in,out] xof cSHAKE256 context.
+ * @param[in,out] xof cSHAKE256 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 _Bool cshake256_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze bytes from cSHAKE256 XOF context.
+ * @brief Squeeze bytes from cSHAKE256 [XOF][] context.
  * @ingroup cshake
  *
  * Squeeze `dst_len` bytes of output into destination buffer `dst` from
- * cSHAKE256 XOF context `xof`.  Can be called iteratively to squeeze
- * output data in chunks.
+ * cSHAKE256 [XOF][] context `xof`.  Can be called iteratively to
+ * squeeze output data in chunks.
  *
- * Note: cSHAKE is used to implement the hash and extendable output
- * functions (XOF) defined in NIST SP 800-185 and should generally not
- * be used directly.
+ * @note cSHAKE is used to implement the hash and [extendable output
+ * functions (XOFs)][xof] defined in [NIST SP 800-185][800-185] and
+ * should generally not be used directly.
  *
- * @param[in,out] xof cSHAKE256 context.
+ * @param[in,out] xof cSHAKE256 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c cshake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
  */
 void cshake256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
@@ -865,16 +1174,26 @@ typedef struct {
  * @ingroup kmac
  *
  * Initialize internal KMAC128 (Keccak Message Authentication Code, as
- * defined in section 4 of NIST SP 800-185) context with configuration
- * parameters `params`, absorb data in buffer `src` of length `src_len`
- * bytes into internal context, then squeeze `dst_len` bytes of output
- * into destination buffer `dst`.
+ * defined in section 4 of [NIST SP 800-185][800-185]) context with
+ * configuration parameters `params`, absorb data in buffer `src` of
+ * length `src_len` bytes into internal context, then squeeze `dst_len`
+ * bytes of output into destination buffer `dst`.
  *
  * @param[in] params KMAC configuration parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac128
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac128(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
@@ -883,7 +1202,7 @@ void kmac128(const kmac_params_t params, const uint8_t *src, const size_t src_le
  * @ingroup kmac
  *
  * Initialize internal KMAC256 (Keccak Message Authentication Code, as
- * defined in section 4 of NIST SP 800-185) XOF context with
+ * defined in section 4 of [NIST SP 800-185][800-185]) context with
  * configuration parameters `params`, absorb data in buffer `src` of
  * length `src_len` bytes into internal context, then squeeze `dst_len`
  * bytes of output into destination buffer `dst`.
@@ -893,24 +1212,44 @@ void kmac128(const kmac_params_t params, const uint8_t *src, const size_t src_le
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac256
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac256(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Initialize KMAC128 XOF context.
+ * @brief Initialize KMAC128 [XOF][] context.
  * @ingroup kmac
  *
- * Initialize KMAC128 XOF (Keccak Message Authentication Code eXtendable
- * Output Function, as defined in section 4.3.1 of NIST SP 800-185)
- * context with configuration parameters `params`.
+ * Initialize KMAC128 [XOF][] (Keccak Message Authentication Code eXtendable
+ * Output Function, as defined in section 4.3.1 of [NIST SP
+ * 800-185][800-185]) context with configuration parameters `params`.
  *
- * Note: KMAC128 and KMAC128 XOF produce different output, because
+ * @note KMAC128 and KMAC128 [XOF][] produce different output, because
  * KMAC128 encodes the fixed output size as part of the input while
- * KMAC128 XOF does not.  See section 4.3.1 of NIST SP 800-185 for
- * details.
+ * KMAC128 [XOF][] does not.  See section 4.3.1 of [NIST SP
+ * 800-185][800-185] for details.
  *
- * @param[out] xof KMAC128 XOF context.
+ * @param[out] xof KMAC128 [XOF][] context.
  * @param[in] params KMAC configuration parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac128_xof_init(sha3_xof_t *xof, const kmac_params_t params);
 
@@ -918,133 +1257,207 @@ void kmac128_xof_init(sha3_xof_t *xof, const kmac_params_t params);
  * @brief Absorb data into KMAC128 XOF context.
  * @ingroup kmac
  *
- * Absorb data in buffer `src` of length `len` bytes into KMAC128 XOF
- * context.  Can be called iteratively to absorb input data in chunks.
+ * Absorb data in buffer `src` of length `len` bytes into KMAC128
+ * [XOF][] context.  Can be called iteratively to absorb input data in
+ * chunks.
  *
- * @param[in,out] xof KMAC128 XOF context.
+ * @param[in,out] xof KMAC128 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 _Bool kmac128_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze data from KMAC128 XOF context.
+ * @brief Squeeze data from KMAC128 [XOF][] context.
  * @ingroup kmac
  *
  * Squeeze `len` bytes of output into destination buffer `dst` from
- * KMAC128 XOF context `xof`.  Can be called iteratively to squeeze
+ * KMAC128 [XOF][] context `xof`.  Can be called iteratively to squeeze
  * output data in chunks.
  *
- * Note: KMAC128 and KMAC128 XOF produce different output, because
+ * @note KMAC128 and KMAC128 [XOF][] produce different output, because
  * KMAC128 encodes the fixed output size as part of the input while
- * KMAC128 XOF does not.  See section 4.3.1 of NIST SP 800-185 for
- * details.
+ * KMAC128 [XOF][] does not.  See section 4.3.1 of [NIST SP
+ * 800-185][800-185] for details.
  *
- * @param[in,out] xof KMAC128 XOF context.
+ * @param[in,out] xof KMAC128 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb data into KMAC128 XOF context, then squeeze bytes out.
+ * @brief Absorb data into KMAC128 [XOF][] context, then squeeze bytes out.
  * @ingroup kmac
  *
- * Initialize internal KMAC128 XOF (Keccak Message Authentication Code
- * eXtendable Output Function, as defined in section 4 of NIST SP
- * 800-185) context with configuration parameters `params`, absorb data
- * in buffer `src` of length `src_len` bytes into internal context, then
- * squeeze `dst_len` bytes of output into destination buffer `dst`.
+ * Initialize internal KMAC128 [XOF][] (Keccak Message Authentication
+ * Code eXtendable Output Function, as defined in section 4 of [NIST SP
+ * 800-185][800-185]) context with configuration parameters `params`,
+ * absorb data in buffer `src` of length `src_len` bytes into internal
+ * context, then squeeze `dst_len` bytes of output into destination
+ * buffer `dst`.
  *
- * Note: KMAC128 and KMAC128 XOF produce different output, because
+ * @note KMAC128 and KMAC128 [XOF][] produce different output, because
  * KMAC128 encodes the fixed output size as part of the input while
- * KMAC128 XOF does not.  See section 4.3.1 of NIST SP 800-185 for
- * details.
+ * KMAC128 [XOF][] does not.  See section 4.3.1 of [NIST SP
+ * 800-185][800-185] for details.
  *
  * @param[in] params KMAC configuration parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac256_xof_once
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac128_xof_once(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Initialize KMAC256 XOF context.
+ * @brief Initialize KMAC256 [XOF][] context.
  * @ingroup kmac
  *
- * Initialize KMAC256 XOF (Keccak Message Authentication Code eXtendable
- * Output Function, as defined in section 4.3.1 of NIST SP 800-185)
- * context with configuration parameters `params`.
+ * Initialize KMAC256 [XOF][] (Keccak Message Authentication Code
+ * eXtendable Output Function, as defined in section 4.3.1 of [NIST SP
+ * 800-185][800-185]) context with configuration parameters `params`.
  *
- * Note: KMAC256 and KMAC256 XOF produce different output, because
+ * @note KMAC256 and KMAC256 [XOF][] produce different output, because
  * KMAC256 encodes the fixed output size as part of the input while
- * KMAC256 XOF does not.  See section 4.3.1 of NIST SP 800-185 for
- * details.
+ * KMAC256 [XOF][] does not.  See section 4.3.1 of [NIST SP
+ * 800-185][800-185] for details.
  *
- * @param[out] xof KMAC256 XOF context.
+ * @param[out] xof KMAC256 [XOF][] context.
  * @param[in] params KMAC configuration parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac256_xof_init(sha3_xof_t *xof, const kmac_params_t params);
 
 /**
- * @brief Absorb data into KMAC256 XOF context.
+ * @brief Absorb data into KMAC256 [XOF][] context.
  * @ingroup kmac
  *
- * Absorb data in buffer `src` of length `len` bytes into KMAC256 XOF
- * context.  Can be called iteratively to absorb input data in chunks.
+ * Absorb data in buffer `src` of length `len` bytes into KMAC256
+ * [XOF][] context.  Can be called iteratively to absorb input data in
+ * chunks.
  *
- * @param[in,out] xof KMAC256 XOF context.
+ * @param[in,out] xof KMAC256 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been squeezed).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 _Bool kmac256_xof_absorb(sha3_xof_t *xof, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze data from KMAC256 XOF context.
+ * @brief Squeeze data from KMAC256 [XOF][] context.
  * @ingroup kmac
  *
  * Squeeze `len` bytes of output into destination buffer `dst` from
- * KMAC256 XOF context `xof`.  Can be called iteratively to squeeze
+ * KMAC256 [XOF][] context `xof`.  Can be called iteratively to squeeze
  * output data in chunks.
  *
- * Note: KMAC256 and KMAC256 XOF produce different output, because
+ * @note KMAC256 and KMAC256 [XOF][] produce different output, because
  * KMAC256 encodes the fixed output size as part of the input while
- * KMAC256 XOF does not.  See section 4.3.1 of NIST SP 800-185 for
- * details.
+ * KMAC256 [XOF][] does not.  See section 4.3.1 of [NIST SP
+ * 800-185][800-185] for details.
  *
  * @ingroup kmac
  *
- * @param[in,out] xof KMAC256 XOF context.
+ * @param[in,out] xof KMAC256 [XOF] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb data into KMAC256 XOF context, then squeeze bytes out.
+ * @brief Absorb data into KMAC256 [XOF][] context, then squeeze bytes out.
  * @ingroup kmac
  *
- * Initialize internal KMAC256 XOF (Keccak Message Authentication Code
- * eXtendable Output Function, as defined in section 4 of NIST SP
- * 800-185) context with configuration parameters `params`, absorb data
- * in buffer `src` of length `src_len` bytes into internal context, then
- * squeeze `dst_len` bytes of output into destination buffer `dst`.
+ * Initialize internal KMAC256 [XOF][] (Keccak Message Authentication
+ * Code eXtendable Output Function, as defined in section 4 of [NIST SP
+ * 800-185][800-185]) context with configuration parameters `params`,
+ * absorb data in buffer `src` of length `src_len` bytes into internal
+ * context, then squeeze `dst_len` bytes of output into destination
+ * buffer `dst`.
  *
- * Note: KMAC256 and KMAC256 XOF produce different output, because
+ * @note KMAC256 and KMAC256 [XOF][] produce different output, because
  * KMAC256 encodes the fixed output size as part of the input while
- * KMAC256 XOF does not.  See section 4.3.1 of NIST SP 800-185 for
- * details.
+ * KMAC256 [XOF][] does not.  See section 4.3.1 of [NIST SP
+ * 800-185][800-185] for details.
  *
  * @param[in] params KMAC configuration parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c kmac256_xof_once
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
+ * [mac]: https://en.wikipedia.org/wiki/Message_authentication_code
+ *   "Message authentication code"
  */
 void kmac256_xof_once(const kmac_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
@@ -1063,8 +1476,11 @@ void kmac256_xof_once(const kmac_params_t params, const uint8_t *src, const size
  */
 
 /**
- * @brief TupleHash tuple element.
+ * @brief Individual element of TupleHash [tuple][].
  * @ingroup tuplehash
+ *
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
  */
 typedef struct {
   const uint8_t *ptr; /**< Pointer to byte string. */
@@ -1083,146 +1499,224 @@ typedef struct {
 } tuplehash_params_t;
 
 /**
- * @brief Absorb data into TupleHash128, then squeeze bytes out.
+ * @brief Absorb [tuple][] and customization string into TupleHash128,
+ * then squeeze bytes out.
  * @ingroup tuplehash
  *
- * Initialize internal TupleHash128 (NIST SP 800-185, section 5) context
- * with configuration parameters `params`, then squeeze `dst_len` bytes
- * of output from internal context into destination buffer `dst`.
+ * Initialize internal TupleHash128 ([NIST SP 800-185][800-185], section
+ * 5) context with configuration parameters `params`, then squeeze `len`
+ * bytes of output from internal context into destination buffer `dst`.
  *
  * @param[in] params TupleHash128 configuration parameters.
  * @param[out] dst Destination buffer.
- * @param[in] dst_len Destination buffer length, in bytes.
+ * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash128
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
  */
-void tuplehash128(const tuplehash_params_t params, uint8_t *dst, const size_t dst_len);
+void tuplehash128(const tuplehash_params_t params, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb data into TupleHash256, then squeeze bytes out.
+ * @brief Absorb [tuple][] and customization string into TupleHash256,
+ * then squeeze bytes out.
  * @ingroup tuplehash
  *
- * Initialize internal TupleHash256 (NIST SP 800-185, section 5) context
- * with configuration parameters `params`, then squeeze `dst_len` bytes
- * of output from internal context into destination buffer `dst`.
+ * Initialize internal TupleHash256 ([NIST SP 800-185][800-185], section
+ * 5) context with configuration parameters `params`, then squeeze `len`
+ * bytes of output from internal context into destination buffer `dst`.
  *
  * @ingroup tuplehash
  *
  * @param[in] params TupleHash256 configuration parameters.
  * @param[out] dst Destination buffer.
- * @param[in] dst_len Destination buffer length, in bytes.
+ * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash256
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
  */
-void tuplehash256(const tuplehash_params_t params, uint8_t *dst, const size_t dst_len);
+void tuplehash256(const tuplehash_params_t params, uint8_t *dst, const size_t len);
 
 /**
- * @brief Initialize a TupleHash128 XOF context.
+ * @brief Initialize a TupleHash128 [XOF][] context.
  * @ingroup tuplehash
  *
- * Initialize TupleHash128 XOF (TupleHash eXtendable Output Function, as
- * defined in section 5.3.1 of NIST SP 800-185) context with
- * configuration parameters `params`.
+ * Initialize TupleHash128 [XOF][] (TupleHash eXtendable Output
+ * Function, as defined in section 5.3.1 of [NIST SP 800-185][800-185])
+ * context with configuration parameters `params`.
  *
- * Note: TupleHash128 and TupleHash128 XOF produce different output,
+ * @note TupleHash128 and TupleHash128 [XOF][] produce different output,
  * because TupleHash128 encodes the fixed output size as part of the
- * input while TupleHash128 XOF does not.  See section 5.3.1 of NIST SP
- * 800-185 for details.
+ * input while TupleHash128 [XOF][] does not.  See section 5.3.1 of
+ * [NIST SP 800-185][800-185] for details.
  *
- * @param[out] xof TupleHash128 XOF context.
+ * @param[out] xof TupleHash128 [XOF][] context.
  * @param[in] params TupleHash configuration parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void tuplehash128_xof_init(sha3_xof_t *xof, const tuplehash_params_t params);
 
 /**
- * @brief Squeeze data from TupleHash128 XOF context.
+ * @brief Squeeze data from TupleHash128 [XOF][] context.
  * @ingroup tuplehash
  *
  * Squeeze `len` bytes of output into destination buffer `dst` from
- * TupleHash128 XOF context `xof`.  Can be called iteratively to squeeze
- * output data in chunks.
+ * TupleHash128 [XOF][] context `xof`.  Can be called iteratively to
+ * squeeze output data in chunks.
  *
- * Note: TupleHash128 and TupleHash128 XOF produce different output,
+ * @note TupleHash128 and TupleHash128 [XOF][] produce different output,
  * because TupleHash128 encodes the fixed output size as part of the
- * input while TupleHash128 XOF does not.  See section 5.3.1 of NIST SP
- * 800-185 for details.
+ * input while TupleHash128 [XOF][] does not.  See section 5.3.1 of
+ * [NIST SP 800-185][800-185] for details.
  *
- * @param[in,out] xof TupleHash128 XOF context.
+ * @param[in,out] xof TupleHash128 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void tuplehash128_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb data into TupleHash128 XOF, then squeeze bytes out.
+ * @brief Absorb data into TupleHash128 [XOF][], then squeeze bytes out.
  * @ingroup tuplehash
  *
- * Initialize internal TupleHash128 XOF (TupleHash eXtendable Output
- * Function, as defined in section 5 of NIST SP 800-185) context with
- * configuration parameters `params`, then squeeze `dst_len` bytes of
- * output into destination buffer `dst`.
+ * Initialize internal TupleHash128 [XOF][] (TupleHash eXtendable Output
+ * Function, as defined in section 5 of [NIST SP 800-185][800-185])
+ * context with configuration parameters `params`, then squeeze
+ * `len` bytes of output into destination buffer `dst`.
  *
- * Note: TupleHash128 and TupleHash128 XOF produce different output,
+ * @note TupleHash128 and TupleHash128 [XOF][] produce different output,
  * because TupleHash128 encodes the fixed output size as part of the
- * input while TupleHash128 XOF does not.  See section 5.3.1 of NIST SP
- * 800-185 for details.
+ * input while TupleHash128 [XOF][] does not.  See section 5.3.1 of
+ * [NIST SP 800-185][800-185] for details.
  *
  * @param[in] params TupleHash128 configuration parameters.
  * @param[out] dst Destination buffer.
- * @param[in] dst_len Destination buffer length, in bytes.
+ * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash128_xof_once
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
-void tuplehash128_xof_once(const tuplehash_params_t params, uint8_t *dst, const size_t dst_len);
+void tuplehash128_xof_once(const tuplehash_params_t params, uint8_t *dst, const size_t len);
 
 /**
- * @brief Initialize a TupleHash256 XOF context.
+ * @brief Initialize a TupleHash256 [XOF][] context.
  * @ingroup tuplehash
  *
- * Initialize TupleHash256 XOF (TupleHash eXtendable Output Function, as
- * defined in section 5.3.1 of NIST SP 800-185) context with
- * configuration parameters `params`.
+ * Initialize TupleHash256 [XOF][] (TupleHash eXtendable Output
+ * Function, as defined in section 5.3.1 of [NIST SP 800-185][800-185])
+ * context with configuration parameters `params`.
  *
- * Note: TupleHash256 and TupleHash256 XOF produce different output,
+ * @note TupleHash256 and TupleHash256 [XOF][] produce different output,
  * because TupleHash256 encodes the fixed output size as part of the
- * input while TupleHash256 XOF does not.  See section 5.3.1 of NIST SP
- * 800-185 for details.
+ * input while TupleHash256 [XOF][] does not.  See section 5.3.1 of
+ * [NIST SP 800-185][800-185] for details.
  *
- * @param[out] xof TupleHash256 XOF context.
+ * @param[out] xof TupleHash256 [XOF][] context.
  * @param[in] params TupleHash configuration parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void tuplehash256_xof_init(sha3_xof_t *xof, const tuplehash_params_t params);
 
 /**
- * @brief Squeeze bytes from a TupleHash256 XOF context.
+ * @brief Squeeze bytes from a TupleHash256 [XOF][] context.
  * @ingroup tuplehash
  *
  * Squeeze `len` bytes of output into destination buffer `dst` from
- * TupleHash256 XOF context `xof`.  Can be called iteratively to squeeze
- * output data in chunks.
+ * TupleHash256 [XOF][] context `xof`.  Can be called iteratively to
+ * squeeze output data in chunks.
  *
- * Note: TupleHash256 and TupleHash256 XOF produce different output,
+ * @note TupleHash256 and TupleHash256 [XOF][] produce different output,
  * because TupleHash256 encodes the fixed output size as part of the
- * input while TupleHash256 XOF does not.  See section 5.3.1 of NIST SP
- * 800-185 for details.
+ * input while TupleHash256 [XOF][] does not.  See section 5.3.1 of
+ * [NIST SP 800-185][800-185] for details.
  *
- * @param[in,out] xof TupleHash256 XOF context.
+ * @param[in,out] xof TupleHash256 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void tuplehash256_xof_squeeze(sha3_xof_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb data into TupleHash256 XOF, then squeeze bytes out.
+ * @brief Absorb data into TupleHash256 [XOF][], then squeeze bytes out.
  * @ingroup tuplehash
  *
- * Initialize internal TupleHash256 XOF (TupleHash eXtendable Output
- * Function, as defined in section 5 of NIST SP 800-185) context with
- * configuration parameters `params`, then squeeze `dst_len` bytes of
- * output into destination buffer `dst`.
+ * Initialize internal TupleHash256 [XOF][] (TupleHash eXtendable Output
+ * Function, as defined in section 5 of [NIST SP 800-185][800-185])
+ * context with configuration parameters `params`, then squeeze `len`
+ * bytes of output into destination buffer `dst`.
  *
- * Note: TupleHash256 and TupleHash256 XOF produce different output,
+ * Note: TupleHash256 and TupleHash256 [XOF][] produce different output,
  * because TupleHash256 encodes the fixed output size as part of the
- * input while TupleHash256 XOF does not.  See section 5.3.1 of NIST SP
- * 800-185 for details.
+ * input while TupleHash256 [XOF][] does not.  See section 5.3.1 of
+ * [NIST SP 800-185][800-185] for details.
  *
  * @param[in] params TupleHash256 configuration parameters.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c tuplehash256_xof_once
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [tuple]: https://en.wikipedia.org/wiki/Tuple
+ *   "Ordered list of elements."
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void tuplehash256_xof_once(const tuplehash_params_t params, uint8_t *dst, const size_t len);
 
@@ -1264,20 +1758,26 @@ typedef struct {
  * @brief Absorb data into ParallelHash128, then squeeze bytes out.
  * @ingroup parallelhash
  *
- * Initialize internal ParallelHash128 (NIST SP 800-185, section 6)
- * context with configuration parameters `params`, then squeeze
- * `dst_len` bytes of output from internal context into destination
- * buffer `dst`.
+ * Initialize internal ParallelHash128 ([NIST SP 800-185][800-185],
+ * section 6) context with configuration parameters `params`, then
+ * squeeze `dst_len` bytes of output from internal context into
+ * destination buffer `dst`.
  *
- * Note: This implementation of ParallelHash128 is sequential, not
- * parallel.
+ * @note This ParallelHash implementation is sequential, not parallel.
  *
- * Note: This implementation of ParallelHash128 is sequential, not
- * @param[in] params ParallelHash128 configuration parameters.
+ * @param[in] params ParallelHash configuration parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash128
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash128(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
@@ -1285,193 +1785,256 @@ void parallelhash128(const parallelhash_params_t params, const uint8_t *src, con
  * @brief Absorb data into ParallelHash256, then squeeze bytes out.
  * @ingroup parallelhash
  *
- * Initialize internal ParallelHash256 (NIST SP 800-185, section 6)
- * context with configuration parameters `params`, then squeeze
- * `dst_len` bytes of output from internal context into destination
- * buffer `dst`.
+ * Initialize internal ParallelHash256 ([NIST SP 800-185][800-185],
+ * section 6) context with configuration parameters `params`, then
+ * squeeze `dst_len` bytes of output from internal context into
+ * destination buffer `dst`.
  *
- * Note: This implementation of ParallelHash256 is sequential, not
- * parallel.
+ * @note This ParallelHash implementation is sequential, not parallel.
  *
  * @ingroup parallelhash
  *
- * @param[in] params ParallelHash256 configuration parameters.
+ * @param[in] params ParallelHash configuration parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash256
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash256(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Initialize a ParallelHash128 XOF context.
+ * @brief Initialize a ParallelHash128 [XOF][] context.
  * @ingroup parallelhash
  *
- * Initialize ParallelHash128 XOF (ParallelHash eXtendable Output
- * Function, as defined in section 6.3.1 of NIST SP 800-185) context
- * with configuration parameters `params`.
+ * Initialize ParallelHash128 [XOF][] (ParallelHash eXtendable Output
+ * Function, as defined in section 6.3.1 of [NIST SP 800-185][800-185])
+ * context with configuration parameters `params`.
  *
- * Note: ParallelHash128 and ParallelHash128 XOF produce different
+ * @note ParallelHash128 and ParallelHash128 [XOF][] produce different
  * output, because ParallelHash128 encodes the fixed output size as part
  * of the input while ParallelHash128 XOF does not.  See section 6.3.1
- * of NIST SP 800-185 for details.
+ * of [NIST SP 800-185][800-185] for details.
  *
- * Note: This implementation of ParallelHash128 is sequential, not
- * parallel.
+ * @note This ParallelHash implementation is sequential, not parallel.
  *
- * @param[out] xof ParallelHash128 XOF context.
+ * @param[out] xof ParallelHash128 [XOF][] context.
  * @param[in] params ParallelHash configuration parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash128_xof_init(parallelhash_t *xof, const parallelhash_params_t params);
 
 /**
- * @brief Absorb data into a ParallelHash128 XOF context.
+ * @brief Absorb data into a ParallelHash128 [XOF][] context.
  * @ingroup parallelhash
  *
  * Absorb data in buffer `src` of length `len` bytes into
- * ParallelHash128 XOF context.  Can be called iteratively to absorb
+ * ParallelHash128 [XOF][] context.  Can be called iteratively to absorb
  * input data in chunks.
  *
- * Note: This implementation of ParallelHash128 is sequential, not
- * parallel.
+ * @note This ParallelHash implementation is sequential, not parallel.
  *
- * @param[in,out] hash ParallelHash128 XOF context.
+ * @param[in,out] hash ParallelHash128 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash128_xof_absorb(parallelhash_t *hash, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze bytes from a ParallelHash128 XOF context.
+ * @brief Squeeze bytes from a ParallelHash128 [XOF][] context.
  * @ingroup parallelhash
  *
  * Squeeze `len` bytes of output into destination buffer `dst` from
- * ParallelHash128 XOF context `xof`.  Can be called iteratively to
+ * ParallelHash128 [XOF][] context `xof`.  Can be called iteratively to
  * squeeze output data in chunks.
  *
- * Note: ParallelHash128 and ParallelHash128 XOF produce different
+ * @note ParallelHash128 and ParallelHash128 [XOF][] produce different
  * output, because ParallelHash128 encodes the fixed output size as part
- * of the input while ParallelHash128 XOF does not.  See section 6.3.1
- * of NIST SP 800-185 for details.
+ * of the input while ParallelHash128 [XOF][] does not.  See section
+ * 6.3.1 of [NIST SP 800-185][800-185] for details.
  *
- * Note: This implementation of ParallelHash128 is sequential, not
- * parallel.
+ * @note This ParallelHash implementation is sequential, not parallel.
  *
  * @param[in,out] xof ParallelHash128 XOF context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash128_xof_squeeze(parallelhash_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb bytes into ParallelHash128 XOF, then squeeze bytes out.
+ * @brief Absorb bytes into ParallelHash128 [XOF][], then squeeze bytes out.
  * @ingroup parallelhash
  *
- * Initialize internal ParallelHash128 XOF (ParallelHash eXtendable
- * Output Function, as defined in section 6.3.1 of NIST SP 800-185)
- * context with configuration parameters `params`, absorb data in buffer
- * `src` of length `src_len` bytes into context, then squeeze `dst_len`
- * bytes of output into destination buffer `dst`.
+ * Initialize internal ParallelHash128 [XOF][] (ParallelHash eXtendable
+ * Output Function, as defined in section 6.3.1 of [NIST SP
+ * 800-185][800-185]) context with configuration parameters `params`,
+ * absorb data in buffer `src` of length `src_len` bytes into context,
+ * then squeeze `dst_len` bytes of output into destination buffer `dst`.
  *
- * Note: ParallelHash128 and ParallelHash128 XOF produce different
+ * @note ParallelHash128 and ParallelHash128 [XOF][] produce different
  * output, because ParallelHash128 encodes the fixed output size as part
- * of the input while ParallelHash128 XOF does not.  See section 6.3.1
- * of NIST SP 800-185 for details.
+ * of the input while ParallelHash128 [XOF][] does not.  See section 6.3.1
+ * of [NIST SP 800-185][800-185] for details.
  *
- * Note: This implementation of ParallelHash128 is sequential, not
- * parallel.
+ * @note This ParallelHash implementation is sequential, not parallel.
  *
  * @param[in] params ParallelHash configuration parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash128_xof_once
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash128_xof_once(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Initialize a ParallelHash256 XOF context.
+ * @brief Initialize a ParallelHash256 [XOF][] context.
  * @ingroup parallelhash
  *
- * Initialize ParallelHash256 XOF (ParallelHash eXtendable Output
- * Function, as defined in section 6.3.1 of NIST SP 800-185) context
- * with configuration parameters `params`.
+ * Initialize ParallelHash256 [XOF][] (ParallelHash eXtendable Output
+ * Function, as defined in section 6.3.1 of [NIST SP 800-185][800-185])
+ * context with configuration parameters `params`.
  *
- * Note: ParallelHash256 and ParallelHash256 XOF produce different
+ * @note ParallelHash256 and ParallelHash256 [XOF][] produce different
  * output, because ParallelHash256 encodes the fixed output size as part
- * of the input while ParallelHash256 XOF does not.  See section 6.3.1
- * of NIST SP 800-185 for details.
+ * of the input while ParallelHash256 [XOF][] does not.  See section 6.3.1
+ * of [NIST SP 800-185][800-185] for details.
  *
- * Note: This implementation of ParallelHash256 is sequential, not
- * parallel.
+ * Note: This ParallelHash implementation is sequential, not parallel.
  *
- * @param[out] xof ParallelHash256 XOF context.
+ * @param[out] xof ParallelHash256 [XOF][] context.
  * @param[in] params ParallelHash configuration parameters.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash256_xof_init(parallelhash_t *xof, const parallelhash_params_t params);
 
 /**
- * @brief Absorb data into a ParallelHash256 XOF context.
+ * @brief Absorb data into a ParallelHash256 [XOF][] context.
  * @ingroup parallelhash
  *
  * Absorb data in buffer `src` of length `len` bytes into
- * ParallelHash256 XOF context.  Can be called iteratively to absorb
+ * ParallelHash256 [XOF][] context.  Can be called iteratively to absorb
  * input data in chunks.
  *
- * Note: This implementation of ParallelHash256 is sequential, not
- * parallel.
+ * @note This ParallelHash implementation is sequential, not parallel.
  *
- * @param[in,out] hash ParallelHash256 XOF context.
+ * @param[in,out] xof ParallelHash256 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
-void parallelhash256_xof_absorb(parallelhash_t *hash, const uint8_t *src, const size_t len);
+void parallelhash256_xof_absorb(parallelhash_t *xof, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze bytes from a ParallelHash256 XOF context.
+ * @brief Squeeze bytes from a ParallelHash256 [XOF][] context.
  * @ingroup parallelhash
  *
  * Squeeze `len` bytes of output into destination buffer `dst` from
- * ParallelHash256 XOF context `xof`.  Can be called iteratively to
+ * ParallelHash256 [XOF][] context `xof`.  Can be called iteratively to
  * squeeze output data in chunks.
  *
- * Note: ParallelHash256 and ParallelHash256 XOF produce different
+ * @note ParallelHash256 and ParallelHash256 [XOF][] produce different
  * output, because ParallelHash256 encodes the fixed output size as part
- * of the input while ParallelHash256 XOF does not.  See section 6.3.1
- * of NIST SP 800-185 for details.
+ * of the input while ParallelHash256 [XOF][] does not.  See section 6.3.1
+ * of [NIST SP 800-185][800-185] for details.
  *
- * Note: This implementation of ParallelHash256 is sequential, not
- * parallel.
+ * Note: This ParallelHash implementation is sequential, not parallel.
  *
- * @param[in,out] xof ParallelHash256 XOF context.
+ * @param[in,out] xof ParallelHash256 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash256_xof_squeeze(parallelhash_t *xof, uint8_t *dst, const size_t len);
 
 /**
- * @brief Absorb bytes into ParallelHash256 XOF, then squeeze bytes out.
+ * @brief Absorb bytes into ParallelHash256 [XOF][], then squeeze bytes out.
  * @ingroup parallelhash
  *
- * Initialize internal ParallelHash256 XOF (ParallelHash eXtendable
- * Output Function, as defined in section 6.3.1 of NIST SP 800-185)
- * context with configuration parameters `params`, absorb `src_len`
- * bytes if input from source buffer `src`, then squeeze `dst_len`
- * bytes of output into destination buffer `dst`.
+ * Initialize internal ParallelHash256 [XOF][] (ParallelHash eXtendable
+ * Output Function, as defined in section 6.3.1 of [NIST SP
+ * 800-185][800-185]) context with configuration parameters `params`,
+ * absorb `src_len` bytes if input from source buffer `src`, then
+ * squeeze `dst_len` bytes of output into destination buffer `dst`.
  *
- * Note: ParallelHash256 and ParallelHash256 XOF produce different
+ * @note ParallelHash256 and ParallelHash256 [XOF][] produce different
  * output, because ParallelHash256 encodes the fixed output size as part
- * of the input while ParallelHash256 XOF does not.  See section 6.3.1
- * of NIST SP 800-185 for details.
+ * of the input while ParallelHash256 [XOF][] does not.  See section
+ * 6.3.1 of [NIST SP 800-185][800-185] for details.
  *
- * Note: This implementation of ParallelHash256 is sequential, not
- * parallel.
+ * Note: This ParallelHash implementation is sequential, not parallel.
  *
  * @param[in] params ParallelHash configuration parameters.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c parallelhash256_xof_once
+ *
+ * [800-185]: https://csrc.nist.gov/pubs/sp/800/185/final
+ *   "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash"
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void parallelhash256_xof_once(const parallelhash_params_t params, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
@@ -1487,29 +2050,36 @@ void parallelhash256_xof_once(const parallelhash_params_t params, const uint8_t
  */
 
 /**
- * @brief Absorb bytes into TurboSHAKE128, then squeeze bytes out.
+ * @brief Absorb bytes into TurboSHAKE128 [XOF][], then squeeze bytes out.
  * @ingroup turboshake
  *
- * Initialize internal TurboSHAKE128 context, absorb `src_len` bytes of
- * input from source buffer `src`, then squeeze `dst_len` bytes of
- * output into destination buffer `dst`.
+ * Initialize internal TurboSHAKE128 [XOF][] context, absorb `src_len`
+ * bytes of input from source buffer `src`, then squeeze `dst_len` bytes
+ * of output into destination buffer `dst`.
  *
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake128
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake128(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Absorb bytes into TurboSHAKE128 with custom padding byte, then squeeze bytes out.
+ * @brief Absorb bytes into TurboSHAKE128 [XOF][] with custom padding
+ * byte, then squeeze bytes out.
  * @ingroup turboshake
  *
- * Initialize internal TurboSHAKE128 context with custom padding byte
- * `pad`, absorb `src_len` bytes of input from source buffer `src`, then
- * squeeze `dst_len` bytes of output into destination buffer `dst`.
+ * Initialize internal TurboSHAKE128 [XOF][] context with custom padding
+ * byte `pad`, absorb `src_len` bytes of input from source buffer `src`,
+ * then squeeze `dst_len` bytes of output into destination buffer `dst`.
  *
- * Note: The padding byte value must be in the range [0x01, 0x7F] and
+ * @note The padding byte value must be in the range [0x01, 0x7F] and
  * can be used for domain separation.
  *
  * @ingroup turboshake
@@ -1519,33 +2089,46 @@ void turboshake128(const uint8_t *src, const size_t src_len, uint8_t *dst, const
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake128_custom
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake128_custom(const uint8_t pad, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Absorb bytes into TurboSHAKE256, then squeeze bytes out.
+ * @brief Absorb bytes into TurboSHAKE256 [XOF][], then squeeze bytes out.
  * @ingroup turboshake
  *
- * Initialize internal TurboSHAKE256 context, absorb `src_len` bytes of
- * input from source buffer `src`, then squeeze `dst_len` bytes of
- * output into destination buffer `dst`.
+ * Initialize internal TurboSHAKE256 [XOF][] context, absorb `src_len`
+ * bytes of input from source buffer `src`, then squeeze `dst_len` bytes
+ * of output into destination buffer `dst`.
  *
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake256
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake256(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief Absorb bytes into TurboSHAKE256 with custom padding byte, then squeeze bytes out.
+ * @brief Absorb bytes into TurboSHAKE256 [XOF][] with custom padding
+ * byte, then squeeze bytes out.
  * @ingroup turboshake
  *
- * Initialize internal TurboSHAKE256 context with custom padding byte
- * `pad`, absorb `src_len` bytes of input from source buffer `src`, then
- * squeeze `dst_len` bytes of output into destination buffer `dst`.
+ * Initialize internal TurboSHAKE256 [XOF][] context with custom padding
+ * byte `pad`, absorb `src_len` bytes of input from source buffer `src`,
+ * then squeeze `dst_len` bytes of output into destination buffer `dst`.
  *
- * Note: The padding byte value must be in the range [0x01, 0x7F] and
+ * @note The padding byte value must be in the range [0x01, 0x7F] and
  * can be used for domain separation.
  *
  * @param[in] pad Padding byte.
@@ -1553,12 +2136,21 @@ void turboshake256(const uint8_t *src, const size_t src_len, uint8_t *dst, const
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake256_custom
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake256_custom(const uint8_t pad, const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
 /**
- * @brief TurboShake XOF context.
+ * @brief TurboShake [XOF][] context (all members are private).
  * @ingroup turboshake
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 typedef struct {
   sha3_xof_t xof; /**< XOF context (private) */
@@ -1566,108 +2158,156 @@ typedef struct {
 } turboshake_t;
 
 /**
- * @brief Initialize TurboSHAKE128 context.
+ * @brief Initialize TurboSHAKE128 [XOF][] context.
  * @ingroup turboshake
  *
- * @param[out] ts TurboSHAKE128 context.
+ * @param[out] ts TurboSHAKE128 [XOF][] context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake128_init(turboshake_t *ts);
 
 /**
- * @brief Initialize TurboSHAKE128 context with custom padding byte.
+ * @brief Initialize TurboSHAKE128 [XOF][] context with custom padding byte.
  * @ingroup turboshake
  *
- * Initialize TurboSHAKE128 context with custom padding byte.  The
+ * Initialize TurboSHAKE128 [XOF][] context with custom padding byte.  The
  * custom padding byte can be used as a domain separator and must be in
  * the range [0x01, 0x7f].
  *
- * @param[out] ts TurboSHAKE128 context.
+ * @param[out] ts TurboSHAKE128 [XOF][] context.
  * @param[in] pad Padding byte (used for domain separation).
  *
  * @return False if the padding byte is out of range and true otherwise.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake128_custom_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 _Bool turboshake128_init_custom(turboshake_t *ts, const uint8_t pad);
 
 /**
- * @brief Absorb data into TurboSHAKE128 context.
+ * @brief Absorb data into TurboSHAKE128 [XOF][] context.
  * @ingroup turboshake
  *
  * Absorb `src_len` bytes of input from source buffer `src` into
- * TurboSHAKE128 context `ts`.  Can be called iteratively to absorb
- * input data in chunks.
+ * TurboSHAKE128 [XOF][] context `ts`.  Can be called iteratively to
+ * absorb input data in chunks.
  *
- * @param[in,out] ts TurboSHAKE128 context.
+ * @param[in,out] ts TurboSHAKE128 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 _Bool turboshake128_absorb(turboshake_t *ts, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze bytes from TurboSHAKE128 context.
+ * @brief Squeeze bytes from TurboSHAKE128 [XOF][] context.
  * @ingroup turboshake
  *
  * Squeeze `dst_len` bytes of output into destination buffer `dst` from
- * TurboSHAKE128 context `ts`.  Can be called iteratively to squeeze
- * output data in chunks.
+ * TurboSHAKE128 [XOF][] context `ts`.  Can be called iteratively to
+ * squeeze output data in chunks.
  *
- * @param[in,out] ts TurboSHAKE128 context.
+ * @param[in,out] ts TurboSHAKE128 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake128_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake128_squeeze(turboshake_t *ts, uint8_t *dst, const size_t len);
 
 /**
- * @brief Initialize TurboSHAKE256 context.
+ * @brief Initialize TurboSHAKE256 [XOF][] context.
  * @ingroup turboshake
  *
- * @param[out] ts TurboSHAKE256 context.
+ * @param[out] ts TurboSHAKE256 [XOF][] context.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake256_init(turboshake_t *ts);
 
 /**
- * @brief Initialize TurboSHAKE256 context with custom padding byte.
+ * @brief Initialize TurboSHAKE256 [XOF] context with custom padding byte.
  * @ingroup turboshake
  *
- * Initialize TurboSHAKE256 context with custom padding byte.  The
- * custom padding byte can be used as a domain separator and must be in
- * the range [0x01, 0x7f].
+ * Initialize TurboSHAKE256 [XOF][] context with custom padding byte.
+ * The custom padding byte can be used as a domain separator and must be
+ * in the range [0x01, 0x7f].
  *
- * @param[out] ts TurboSHAKE256 context.
+ * @param[out] ts TurboSHAKE256 [XOF][] context.
  * @param[in] pad Padding byte (used for domain separation).
  *
  * @return False if the padding byte is out of range and true otherwise.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake256_custom_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 _Bool turboshake256_init_custom(turboshake_t *ts, const uint8_t pad);
 
 /**
- * @brief Absorb data into TurboSHAKE256 context.
+ * @brief Absorb data into TurboSHAKE256 [XOF][] context.
  * @ingroup turboshake
  *
- * Absorb `src_len` bytes of input from source buffer `src` into
- * TurboSHAKE256 context `ts`.  Can be called iteratively to absorb
- * input data in chunks.
+ * Absorb `len` bytes of input from source buffer `src` into
+ * TurboSHAKE256 [XOF][] context `ts`.  Can be called iteratively to
+ * absorb input data in chunks.
  *
- * @param[in,out] ts TurboSHAKE256 context.
+ * @param[in,out] ts TurboSHAKE256 [XOF][] context.
  * @param[in] src Source buffer.
  * @param[in] len Source buffer length, in bytes.
  *
  * @return True if data was absorbed, and false otherwise (e.g., if context has already been finalized).
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 _Bool turboshake256_absorb(turboshake_t *ts, const uint8_t *src, const size_t len);
 
 /**
- * @brief Squeeze bytes from TurboSHAKE256 context.
+ * @brief Squeeze bytes from TurboSHAKE256 [XOF][] context.
  * @ingroup turboshake
  *
- * Squeeze `dst_len` bytes of output into destination buffer `dst` from
+ * Squeeze `len` bytes of output into destination buffer `dst` from
  * TurboSHAKE256 context `ts`.  Can be called iteratively to squeeze
  * output data in chunks.
  *
- * @param[in,out] ts TurboSHAKE256 context.
+ * @param[in,out] ts TurboSHAKE256 [XOF][] context.
  * @param[out] dst Destination buffer.
  * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c turboshake256_xof
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 void turboshake256_squeeze(turboshake_t *ts, uint8_t *dst, const size_t len);
 
@@ -1684,8 +2324,11 @@ void turboshake256_squeeze(turboshake_t *ts, uint8_t *dst, const size_t len);
  */
 
 /**
- * @brief KangarooTwelve context.
+ * @brief KangarooTwelve [XOF][] context (all members are private).
  * @ingroup k12
+ *
+ * [xof]: https://en.wikipedia.org/wiki/Extendable-output_function
+ *   "Extendable-Output Function (XOF)"
  */
 typedef struct {
   turboshake_t ts; /**< Internal turboshake context (private) */
@@ -1703,6 +2346,9 @@ typedef struct {
  * @param[in] src_len Source buffer length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c k12_once
  */
 void k12_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size_t dst_len);
 
@@ -1721,6 +2367,9 @@ void k12_once(const uint8_t *src, const size_t src_len, uint8_t *dst, const size
  * @param[in] custom_len Custom string length, in bytes.
  * @param[out] dst Destination buffer.
  * @param[in] dst_len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c k12_custom_once
  */
 void k12_custom_once(const uint8_t *src, const size_t src_len, const uint8_t *custom, const size_t custom_len, uint8_t *dst, const size_t dst_len);
 
@@ -1732,14 +2381,16 @@ void k12_custom_once(const uint8_t *src, const size_t src_len, const uint8_t *cu
  * `src_len` bytes and custom string `custom` of length `custom_len`
  * bytes.
  *
- * Note: This implementation of KangarooTwelve is sequential, not
- * parallel.
+ * @note This KangarooTwelve implementation is sequential, not parallel.
  *
  * @param[out] k12 KangarooTwelve context.
  * @param[in] src Source buffer.
  * @param[in] src_len Source buffer length, in bytes.
  * @param[in] custom Custom string buffer.
  * @param[in] custom_len Custom string length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c k12_xof
  */
 void k12_init(k12_t *k12, const uint8_t *src, const size_t src_len, const uint8_t *custom, const size_t custom_len);
 
@@ -1751,14 +2402,16 @@ void k12_init(k12_t *k12, const uint8_t *src, const size_t src_len, const uint8_
  * KangarooTwelve context `k12`.  Can be called iteratively to squeeze
  * output data in chunks.
  *
- * Note: This implementation of KangarooTwelve is sequential, not
- * parallel.
+ * @note This KangarooTwelve implementation is sequential, not parallel.
  *
  * @param[in,out] k12 KangarooTwelve context.
  * @param[out] dst Destination buffer.
- * @param[in] dst_len Destination buffer length, in bytes.
+ * @param[in] len Destination buffer length, in bytes.
+ *
+ * Example:
+ * @snippet{trimleft} 06-all/all-fns.c k12_xof
  */
-void k12_squeeze(k12_t *k12, uint8_t *dst, const size_t dst_len);
+void k12_squeeze(k12_t *k12, uint8_t *dst, const size_t len);
 
 #ifdef __cplusplus
 }