From d6f56cea82cde7f56df9fb220eb529b96b702fbb Mon Sep 17 00:00:00 2001
From: "Matthias J. Kannwischer" <matthias@zerorisc.com>
Date: Wed, 3 Jun 2026 21:19:42 +0800
Subject: [PATCH] mldsa: annotate functions with FIPS 204 algorithm references

Add `@spec{Implements @[FIPS204, Algorithm N, Name]}` annotations linking
functions to their FIPS 204 algorithms.

Also normalize the existing sign.h `@spec` references from
`@[FIPS204 Algorithm N (Name)]` to the comma style used throughout.

Covers Algorithms 1-8, 16-36, 39-42, 44, 45, 48, 49. The remaining algorithms
have no dedicated function: 9-15 (IntegerToBits/.../CoeffFromHalfByte),
37/38 (HighBits/LowBits, subsumed in Decompose), 43 (BitRev8, precomputed
zetas), and 46/47 (AddVectorNTT/ScalarVectorNTT, applied inline in sign.c as
loops over AddNTT/MultiplyNTT).

 - Resolves https://github.com/pq-code-package/mldsa-native/issues/696

Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>
---
 BIBLIOGRAPHY.md          |  5 +++++
 mldsa/src/packing.h      | 34 ++++++++++++++++++++++++++++++++++
 mldsa/src/poly.h         | 30 ++++++++++++++++++++++++++++++
 mldsa/src/poly_kl.h      | 27 +++++++++++++++++++++++++++
 mldsa/src/polyvec.h      | 17 +++++++++++++++++
 mldsa/src/polyvec_lazy.c |  3 +++
 mldsa/src/reduce.h       | 12 ++++++++++++
 mldsa/src/rounding.h     | 10 +++++++++-
 mldsa/src/sign.c         | 13 +++++++++++++
 mldsa/src/sign.h         | 16 +++++++++-------
 10 files changed, 159 insertions(+), 8 deletions(-)

diff --git a/BIBLIOGRAPHY.md b/BIBLIOGRAPHY.md
index 3c6703846..8057c0382 100644
--- a/BIBLIOGRAPHY.md
+++ b/BIBLIOGRAPHY.md
@@ -108,9 +108,14 @@ source code and documentation.
   - [mldsa/src/ct.h](mldsa/src/ct.h)
   - [mldsa/src/fips202/fips202.c](mldsa/src/fips202/fips202.c)
   - [mldsa/src/fips202/fips202x4.c](mldsa/src/fips202/fips202x4.c)
+  - [mldsa/src/packing.h](mldsa/src/packing.h)
   - [mldsa/src/poly.c](mldsa/src/poly.c)
+  - [mldsa/src/poly.h](mldsa/src/poly.h)
   - [mldsa/src/poly_kl.c](mldsa/src/poly_kl.c)
+  - [mldsa/src/poly_kl.h](mldsa/src/poly_kl.h)
+  - [mldsa/src/polyvec.h](mldsa/src/polyvec.h)
   - [mldsa/src/polyvec_lazy.c](mldsa/src/polyvec_lazy.c)
+  - [mldsa/src/reduce.h](mldsa/src/reduce.h)
   - [mldsa/src/rounding.h](mldsa/src/rounding.h)
   - [mldsa/src/sign.c](mldsa/src/sign.c)
   - [mldsa/src/sign.h](mldsa/src/sign.h)
diff --git a/mldsa/src/packing.h b/mldsa/src/packing.h
index a039db99d..74f2a0316 100644
--- a/mldsa/src/packing.h
+++ b/mldsa/src/packing.h
@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_PACKING_H
 #define MLD_PACKING_H
 
@@ -13,6 +23,9 @@
 /**
  * Bit-pack the s1 component into the secret key.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 24, skEncode] (s1
+ * component).}
+ *
  * @param[out] sk Output byte array.
  * @param[in]  s1 Pointer to vector s1.
  */
@@ -34,6 +47,9 @@ __contract__(
  * s1 must already be packed via mld_pack_sk_s1, and t0 via
  * mld_compute_pack_t0_t1.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 24, skEncode] (rho, key, tr,
+ * s2 components).}
+ *
  * @param[out] sk  Output byte array.
  * @param[in]  rho Byte array containing rho.
  * @param[in]  tr  Byte array containing tr.
@@ -64,6 +80,9 @@ __contract__(
 /**
  * Bit-pack challenge c into sig = (c, z, h).
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 26, sigEncode] (c
+ * component).}
+ *
  * @param[out] sig Output byte array.
  * @param[in]  c   Pointer to challenge hash.
  */
@@ -80,6 +99,10 @@ __contract__(
 /**
  * Compute hints from (w0, w1) and pack them into the hint section of sig.
  *
+ * @spec{Implements @[FIPS204, Algorithm 20, HintBitPack], computing the hints
+ * via @[FIPS204, Algorithm 39, MakeHint] (h component of @[FIPS204,
+ * Algorithm 26, sigEncode]).}
+ *
  * @param[in,out] sig Byte array containing signature.
  * @param[in]     w0  Pointer to low part of input vector.
  * @param[in]     w1  Pointer to high part of input vector.
@@ -109,6 +132,9 @@ __contract__(
  * The c and h components are packed separately using mld_pack_sig_c and
  * mld_pack_sig_h.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 26, sigEncode] (one
+ * polynomial of the z component).}
+ *
  * @param[in,out] sig Output byte array.
  * @param[in]     zi  Pointer to a single polynomial in z.
  * @param         i   Index of zi in vector z.
@@ -131,6 +157,9 @@ __contract__(
  * Unpack a single polynomial of the t1 component of a public key
  * pk = (rho, t1).
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 23, pkDecode] (one polynomial
+ * of t1).}
+ *
  * @param[out] t1 Pointer to output polynomial t1[i].
  * @param[in]  pk Byte array containing bit-packed pk.
  * @param      i  Row index, must be < MLDSA_K.
@@ -155,6 +184,8 @@ __contract__(
  *
  * NOTE: In REDUCE_RAM mode, s1/s2/t0 borrow from sk rather than copying.
  *
+ * @spec{Implements @[FIPS204, Algorithm 25, skDecode].}
+ *
  * @param[out] rho Output byte array for rho.
  * @param[out] tr  Output byte array for tr.
  * @param[out] key Output byte array for key.
@@ -215,6 +246,9 @@ __contract__(
  * call returns MLD_ERR_FAIL the encoding is malformed and the signature must
  * be rejected.
  *
+ * @spec{Implements @[FIPS204, Algorithm 21, HintBitUnpack] (one row; part of
+ * @[FIPS204, Algorithm 27, sigDecode]).}
+ *
  * @param[out] h   Pointer to output polynomial h[i].
  * @param[in]  sig Signature buffer.
  * @param      i   Row index, must be < MLDSA_K.
diff --git a/mldsa/src/poly.h b/mldsa/src/poly.h
index bb0e45251..d85b08261 100644
--- a/mldsa/src/poly.h
+++ b/mldsa/src/poly.h
@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_POLY_H
 #define MLD_POLY_H
 
@@ -64,6 +74,8 @@ __contract__(
 /**
  * Add polynomials. No modular reduction is performed.
  *
+ * @spec{Implements @[FIPS204, Algorithm 44, AddNTT].}
+ *
  * @param[in,out] r Pointer to input-output polynomial to be added to.
  * @param[in]     b Pointer to input polynomial that should be added to r.
  *                  Must be disjoint from r.
@@ -136,6 +148,8 @@ __contract__(
  * In-place forward NTT. Output coefficients are bounded by MLD_NTT_BOUND in
  * absolute value.
  *
+ * @spec{Implements @[FIPS204, Algorithm 41, NTT].}
+ *
  * @param[in,out] a Pointer to input/output polynomial.
  */
 MLD_INTERNAL_API
@@ -155,6 +169,8 @@ __contract__(
  * Input coefficients need to be less than MLDSA_Q in absolute value and
  * output coefficients are bounded by MLD_INTT_BOUND.
  *
+ * @spec{Implements @[FIPS204, Algorithm 42, NTT^{-1}].}
+ *
  * @param[in,out] a Pointer to input/output polynomial.
  */
 MLD_INTERNAL_API
@@ -174,6 +190,8 @@ __contract__(
  * multiplication of resulting polynomial by 2^{-32}. Destructive in the first
  * argument.
  *
+ * @spec{Implements @[FIPS204, Algorithm 45, MultiplyNTT].}
+ *
  * @param[in,out] a Pointer to first input/output polynomial. On entry, holds
  *                  the first multiplicand; on exit, holds the product
  *                  a * b * 2^{-32}.
@@ -225,6 +243,8 @@ __contract__(
  * Sample polynomial with uniformly random coefficients in [0, MLDSA_Q-1] by
  * performing rejection sampling on the output stream of SHAKE128(seed|nonce).
  *
+ * @spec{Implements @[FIPS204, Algorithm 30, RejNTTPoly].}
+ *
  * @param[out] a    Pointer to output polynomial.
  * @param[in]  seed Byte array with seed of length MLDSA_SEEDBYTES and the
  *                  packed 2-byte nonce.
@@ -245,6 +265,8 @@ __contract__(
  * Generate four polynomials using rejection sampling on (pseudo-)uniformly
  * random bytes sampled from a seed.
  *
+ * @spec{Implements @[FIPS204, Algorithm 30, RejNTTPoly] (four-way batched).}
+ *
  * @param[out] vec0 Pointer to first polynomial to be sampled.
  * @param[out] vec1 Pointer to second polynomial to be sampled.
  * @param[out] vec2 Pointer to third polynomial to be sampled.
@@ -280,6 +302,8 @@ __contract__(
  * Bit-pack polynomial t1 with coefficients fitting in 10 bits. Input
  * coefficients are assumed to be standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 16, SimpleBitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYT1_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -300,6 +324,8 @@ __contract__(
  * Unpack polynomial t1 with 10-bit coefficients. Output coefficients are
  * standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 18, SimpleBitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */
@@ -318,6 +344,8 @@ __contract__(
 /**
  * Bit-pack polynomial t0 with coefficients in ]-2^{MLDSA_D-1}, 2^{MLDSA_D-1}].
  *
+ * @spec{Implements @[FIPS204, Algorithm 17, BitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYT0_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -337,6 +365,8 @@ __contract__(
 /**
  * Unpack polynomial t0 with coefficients in ]-2^{MLDSA_D-1}, 2^{MLDSA_D-1}].
  *
+ * @spec{Implements @[FIPS204, Algorithm 19, BitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */
diff --git a/mldsa/src/poly_kl.h b/mldsa/src/poly_kl.h
index 2e5163ce1..9462bb876 100644
--- a/mldsa/src/poly_kl.h
+++ b/mldsa/src/poly_kl.h
@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_POLY_KL_H
 #define MLD_POLY_KL_H
 
@@ -68,6 +78,9 @@ __contract__(
  * [-MLDSA_ETA, MLDSA_ETA] by performing rejection sampling on the output
  * stream from SHAKE256(seed|nonce_i).
  *
+ * @spec{Implements @[FIPS204, Algorithm 31, RejBoundedPoly] (four-way
+ * batched).}
+ *
  * @param[out] r0     Pointer to first output polynomial.
  * @param[out] r1     Pointer to second output polynomial.
  * @param[out] r2     Pointer to third output polynomial.
@@ -107,6 +120,8 @@ __contract__(
  * [-MLDSA_ETA, MLDSA_ETA] by performing rejection sampling on the output
  * stream from SHAKE256(seed|nonce).
  *
+ * @spec{Implements @[FIPS204, Algorithm 31, RejBoundedPoly].}
+ *
  * @param[out] r     Pointer to output polynomial.
  * @param[in]  seed  Byte array with seed of length MLDSA_CRHBYTES.
  * @param      nonce Nonce.
@@ -198,6 +213,8 @@ __contract__(
  * Implementation of H. Samples polynomial with MLDSA_TAU nonzero coefficients
  * in {-1, 1} using the output stream of SHAKE256(seed).
  *
+ * @spec{Implements @[FIPS204, Algorithm 29, SampleInBall].}
+ *
  * @param[out] c    Pointer to output polynomial.
  * @param[in]  seed Byte array containing seed of length MLDSA_CTILDEBYTES.
  */
@@ -217,6 +234,8 @@ __contract__(
 /**
  * Bit-pack polynomial with coefficients in [-MLDSA_ETA, MLDSA_ETA].
  *
+ * @spec{Implements @[FIPS204, Algorithm 17, BitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYETA_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -252,6 +271,8 @@ __contract__(
 /**
  * Unpack polynomial with coefficients in [-MLDSA_ETA, MLDSA_ETA].
  *
+ * @spec{Implements @[FIPS204, Algorithm 19, BitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */
@@ -271,6 +292,8 @@ __contract__(
  * Bit-pack polynomial with coefficients in
  * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
  *
+ * @spec{Implements @[FIPS204, Algorithm 17, BitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYZ_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
@@ -291,6 +314,8 @@ __contract__(
  * Unpack polynomial z with coefficients in
  * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1].
  *
+ * @spec{Implements @[FIPS204, Algorithm 19, BitUnpack].}
+ *
  * @param[out] r Pointer to output polynomial.
  * @param[in]  a Byte array with bit-packed polynomial.
  */
@@ -308,6 +333,8 @@ __contract__(
  * Bit-pack polynomial w1 with coefficients in [0, 15] or [0, 43]. Input
  * coefficients are assumed to be standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 16, SimpleBitPack].}
+ *
  * @param[out] r Pointer to output byte array with at least
  *               MLDSA_POLYW1_PACKEDBYTES bytes.
  * @param[in]  a Pointer to input polynomial.
diff --git a/mldsa/src/polyvec.h b/mldsa/src/polyvec.h
index 7ad461712..1a138b0af 100644
--- a/mldsa/src/polyvec.h
+++ b/mldsa/src/polyvec.h
@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_POLYVEC_H
 #define MLD_POLYVEC_H
 
@@ -33,6 +43,8 @@ typedef struct
  * [-(MLDSA_GAMMA1 - 1), MLDSA_GAMMA1] by unpacking output stream of
  * SHAKE256(seed|nonce).
  *
+ * @spec{Implements @[FIPS204, Algorithm 34, ExpandMask].}
+ *
  * @param[out] v     Pointer to output vector.
  * @param[in]  seed  Byte array with seed of length MLDSA_CRHBYTES.
  * @param      nonce 16-bit nonce.
@@ -89,6 +101,9 @@ __contract__(
  * The second input "v" is assumed to be output of an NTT, and hence must have
  * coefficients bounded by [-(MLD_NTT_BOUND-1), MLD_NTT_BOUND-1] inclusive.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 48, MatrixVectorNTT]
+ * (one output polynomial; multiply-accumulate of two NTT-domain vectors).}
+ *
  * @param[out] w Output polynomial.
  * @param[in]  u Pointer to first input vector.
  * @param[in]  v Pointer to second input vector.
@@ -290,6 +305,8 @@ __contract__(
  * Bit-pack polynomial vector w1 with coefficients in [0, 15] or [0, 43]. Input
  * coefficients are assumed to be standard representatives.
  *
+ * @spec{Implements @[FIPS204, Algorithm 28, w1Encode].}
+ *
  * @param[out] r  Pointer to output byte array with at least
  *                MLDSA_K * MLDSA_POLYW1_PACKEDBYTES bytes.
  * @param[in]  w1 Pointer to input polynomial vector.
diff --git a/mldsa/src/polyvec_lazy.c b/mldsa/src/polyvec_lazy.c
index 6e0971fb6..d85761ea0 100644
--- a/mldsa/src/polyvec_lazy.c
+++ b/mldsa/src/polyvec_lazy.c
@@ -29,6 +29,9 @@
  * of seed_ext. This function writes the domain-separation bytes
  * seed_ext[SEEDBYTES..+2] = {l, k} before sampling.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 32, ExpandA] (samples one
+ * matrix entry via @[FIPS204, Algorithm 30, RejNTTPoly]).}
+ *
  * @param[out]    p        Pointer to output polynomial.
  * @param[in,out] seed_ext Seed buffer pre-filled with rho in the first
  *                         MLDSA_SEEDBYTES; the final two bytes are
diff --git a/mldsa/src/reduce.h b/mldsa/src/reduce.h
index bb86d0705..6ece626dc 100644
--- a/mldsa/src/reduce.h
+++ b/mldsa/src/reduce.h
@@ -2,6 +2,16 @@
  * Copyright (c) The mldsa-native project authors
  * SPDX-License-Identifier: Apache-2.0 OR ISC OR MIT
  */
+
+/* References
+ * ==========
+ *
+ * - [FIPS204]
+ *   FIPS 204 Module-Lattice-Based Digital Signature Standard
+ *   National Institute of Standards and Technology
+ *   https://csrc.nist.gov/pubs/fips/204/final
+ */
+
 #ifndef MLD_REDUCE_H
 #define MLD_REDUCE_H
 
@@ -24,6 +34,8 @@
  * Generic Montgomery reduction; given a 64-bit integer a, computes a 32-bit
  * integer congruent to a * R^-1 mod MLDSA_Q, where R=2^32.
  *
+ * @spec{Implements @[FIPS204, Algorithm 49, MontgomeryReduce].}
+ *
  * @param a Input integer to be reduced, of absolute value smaller or equal
  *          to INT64_MAX - 2^31 * MLDSA_Q.
  *
diff --git a/mldsa/src/rounding.h b/mldsa/src/rounding.h
index 21fae3c98..55fd10034 100644
--- a/mldsa/src/rounding.h
+++ b/mldsa/src/rounding.h
@@ -38,6 +38,8 @@
  * -2^{MLDSA_D-1} < a0 <= 2^{MLDSA_D-1}. Assumes a to be standard
  * representative.
  *
+ * @spec{Implements @[FIPS204, Algorithm 35, Power2Round].}
+ *
  * @reference{In the reference implementation, a1 is passed as a return value
  * instead.}
  *
@@ -69,6 +71,8 @@ __contract__(
  * -MLDSA_GAMMA2 <= a0 = a mod^+ MLDSA_Q - MLDSA_Q < 0. Assumes a to be
  * standard representative.
  *
+ * @spec{Implements @[FIPS204, Algorithm 36, Decompose].}
+ *
  * @reference{In the reference implementation, a1 is passed as a return value
  * instead.}
  *
@@ -84,7 +88,7 @@ __contract__(
   assigns(memory_slice(a0, sizeof(int32_t)))
   assigns(memory_slice(a1, sizeof(int32_t)))
   /* a0 = -MLDSA_GAMMA2 can only occur when (q-1) = a - (a mod MLDSA_GAMMA2),
-   * then a1=1; and a0 = a - (a mod MLDSA_GAMMA2) - 1 (@[FIPS204, Algorithm 36 (Decompose)]) */
+   * then a1=1; and a0 = a - (a mod MLDSA_GAMMA2) - 1 (@[FIPS204, Algorithm 36, Decompose]) */
   ensures(*a0 >= -MLDSA_GAMMA2  && *a0 <= MLDSA_GAMMA2)
   ensures(*a1 >= 0 && *a1 < (MLDSA_Q-1)/(2*MLDSA_GAMMA2))
   ensures((*a1 * 2 * MLDSA_GAMMA2 + *a0 - a) % MLDSA_Q == 0)
@@ -174,6 +178,8 @@ __contract__(
  * Compute hint bit indicating whether the low bits of the input element
  * overflow into the high bits.
  *
+ * @spec{Implements @[FIPS204, Algorithm 39, MakeHint].}
+ *
  * @param a0 Low bits of input element.
  * @param a1 High bits of input element.
  *
@@ -197,6 +203,8 @@ __contract__(
 /**
  * Correct high bits according to hint.
  *
+ * @spec{Implements @[FIPS204, Algorithm 40, UseHint].}
+ *
  * @param a    Input element.
  * @param hint Hint bit.
  *
diff --git a/mldsa/src/sign.c b/mldsa/src/sign.c
index f5e1d3f08..2afab6804 100644
--- a/mldsa/src/sign.c
+++ b/mldsa/src/sign.c
@@ -146,6 +146,16 @@ static int mld_check_pct(uint8_t const pk[MLDSA_CRYPTO_PUBLICKEYBYTES],
 }
 #endif /* !MLD_CONFIG_KEYGEN_PCT */
 
+/**
+ * Sample the short secret vectors s1 (length MLDSA_L) and s2 (length MLDSA_K)
+ * with coefficients in [-MLDSA_ETA, MLDSA_ETA] from the seed.
+ *
+ * @spec{Implements @[FIPS204, Algorithm 33, ExpandS].}
+ *
+ * @param[out] s1   Output vector s1.
+ * @param[out] s2   Output vector s2.
+ * @param[in]  seed Byte array with seed of length MLDSA_CRHBYTES.
+ */
 static void mld_sample_s1_s2(mld_polyvecl *s1, mld_polyveck *s2,
                              const uint8_t seed[MLDSA_CRHBYTES])
 __contract__(
@@ -204,6 +214,9 @@ __contract__(
  * t1[k] via power2round, and bit-pack t1[k] into pk_t1 and t0[k] into the
  * t0_packed buffer. Used by both keygen and pk_from_sk.
  *
+ * @spec{Partially implements @[FIPS204, Algorithm 22, pkEncode] (t1) and
+ * @[FIPS204, Algorithm 24, skEncode] (t0).}
+ *
  * @param[out] pk_t1     Output buffer for packed t1 (size
  *                       MLDSA_K * MLDSA_POLYT1_PACKEDBYTES; i.e. the t1
  *                       region of pk).
diff --git a/mldsa/src/sign.h b/mldsa/src/sign.h
index 68135380e..8b836ba80 100644
--- a/mldsa/src/sign.h
+++ b/mldsa/src/sign.h
@@ -93,7 +93,7 @@
  * When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test
  * (PCT) as required by FIPS 140-3 IG.
  *
- * @spec{Implements @[FIPS204 Algorithm 6 (ML-DSA.KeyGen_internal)].}
+ * @spec{Implements @[FIPS204, Algorithm 6, ML-DSA.KeyGen_internal].}
  *
  * @param[out] pk      Output public key.
  * @param[out] sk      Output private key.
@@ -137,7 +137,7 @@ __contract__(
  * When MLD_CONFIG_KEYGEN_PCT is set, performs a Pairwise Consistency Test
  * (PCT) as required by FIPS 140-3 IG.
  *
- * @spec{Implements @[FIPS204 Algorithm 1 (ML-DSA.KeyGen)].}
+ * @spec{Implements @[FIPS204, Algorithm 1, ML-DSA.KeyGen].}
  *
  * @param[out] pk      Output public key.
  * @param[out] sk      Output private key.
@@ -180,6 +180,8 @@ __contract__(
  * If the returned value is non-zero, then the values of *sig and *siglen
  * should not be referenced.
  *
+ * @spec{Implements @[FIPS204, Algorithm 7, ML-DSA.Sign_internal].}
+ *
  * @param[out] sig        Output signature.
  * @param[out] siglen     Pointer to output length of signature.
  * @param[in]  m          Pointer to message to be signed (when
@@ -244,7 +246,7 @@ __contract__(
  * ML-DSA. If you require the deterministic variant, use
  * mld_sign_signature_internal directly.
  *
- * @spec{Implements @[FIPS204 Algorithm 2 (ML-DSA.Sign)].}
+ * @spec{Implements @[FIPS204, Algorithm 2, ML-DSA.Sign].}
  *
  * @param[out] sig     Output signature.
  * @param[out] siglen  Pointer to output length of signature.
@@ -296,7 +298,7 @@ __contract__(
  * variant; for the deterministic variant, use mld_sign_signature_internal
  * directly with externalmu set to non-zero and an all-zero rnd.
  *
- * @spec{Implements @[FIPS204 Algorithm 2 (ML-DSA.Sign external mu variant)].}
+ * @spec{Implements @[FIPS204, Algorithm 2, ML-DSA.Sign external mu variant].}
  *
  * @param[out] sig     Output signature.
  * @param[out] siglen  Pointer to output length of signature.
@@ -383,7 +385,7 @@ __contract__(
 /**
  * Verify signature.
  *
- * @spec{Implements @[FIPS204 Algorithm 8 (ML-DSA.Verify_internal)].}
+ * @spec{Implements @[FIPS204, Algorithm 8, ML-DSA.Verify_internal].}
  *
  * @param[in] sig        Pointer to input signature.
  * @param     siglen     Length of signature.
@@ -432,7 +434,7 @@ __contract__(
 /**
  * Verify signature.
  *
- * @spec{Implements @[FIPS204 Algorithm 3 (ML-DSA.Verify)].}
+ * @spec{Implements @[FIPS204, Algorithm 3, ML-DSA.Verify].}
  *
  * @param[in] sig     Pointer to input signature.
  * @param     siglen  Length of signature.
@@ -474,7 +476,7 @@ __contract__(
  * 0x00 || ctxlen || ctx || msg for pure ML-DSA). The same mu must have been
  * used at signing time.
  *
- * @spec{Implements @[FIPS204 Algorithm 3 (ML-DSA.Verify external mu variant)].}
+ * @spec{Implements @[FIPS204, Algorithm 3, ML-DSA.Verify external mu variant].}
  *
  * @param[in] sig     Pointer to input signature.
  * @param     siglen  Length of signature.