pq_crypto 0.6.1 → 0.6.3

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/native/x86_64/src/{tomont.S → tomont_avx2_asm.S}

@@ -28,17 +28,13 @@
 
 /*
  * WARNING: This file is auto-derived from the mlkem-native source file
- *   dev/x86_64/src/tomont.S using scripts/simpasm. Do not modify it directly.
+ *   dev/x86_64/src/tomont_avx2_asm.S using scripts/simpasm. Do not modify it directly.
  */
 
-#if defined(__ELF__)
-.section .note.GNU-stack,"",@progbits
-#endif
-
 .text
 .balign 4
-.global MLK_ASM_NAMESPACE(tomont_avx2)
-MLK_ASM_FN_SYMBOL(tomont_avx2)
+.global MLK_ASM_NAMESPACE(tomont_avx2_asm)
+MLK_ASM_FN_SYMBOL(tomont_avx2_asm)
 
         .cfi_startproc
         movl $0xd010d01, %eax        # imm = 0xD010D01
@@ -149,7 +145,11 @@ MLK_ASM_FN_SYMBOL(tomont_avx2)
         retq
         .cfi_endproc
 
-MLK_ASM_FN_SIZE(tomont_avx2)
+MLK_ASM_FN_SIZE(tomont_avx2_asm)
 
 #endif /* MLK_ARITH_BACKEND_X86_64_DEFAULT && !MLK_CONFIG_MULTILEVEL_NO_SHARED \
         */
+
+#if defined(__ELF__)
+.section .note.GNU-stack,"",%progbits
+#endif

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/poly.c

@@ -28,22 +28,18 @@
 #include "symmetric.h"
 #include "verify.h"
 
-/*************************************************
- * Name:        mlk_fqmul
+/**
+ * Montgomery multiplication modulo MLKEM_Q.
  *
- * Description: Montgomery multiplication modulo MLKEM_Q
+ * @reference{`fqmul()` in the reference implementation @[REF].}
  *
- * Arguments:   - int16_t a: first factor
- *                  Can be any int16_t.
- *              - int16_t b: second factor.
- *                  Must be signed canonical (abs value <(MLKEM_Q+1)/2)
+ * @param a First factor. Can be any int16_t.
+ * @param b Second factor. Must be signed canonical
+ *          (abs value < (MLKEM_Q+1)/2).
  *
- * Returns 16-bit integer congruent to a*b*R^{-1} mod MLKEM_Q, and
- * smaller than MLKEM_Q in absolute value.
- *
- **************************************************/
-
-/* Reference: `fqmul()` in the reference implementation @[REF]. */
+ * @return 16-bit integer congruent to a*b*R^{-1} mod MLKEM_Q, and
+ *         smaller than MLKEM_Q in absolute value.
+ */
 static MLK_INLINE int16_t mlk_fqmul(int16_t a, int16_t b)
 __contract__(
   requires(b > -MLKEM_Q_HALF && b < MLKEM_Q_HALF)
@@ -65,20 +61,17 @@ __contract__(
   return res;
 }
 
-/*************************************************
- * Name:        mlk_barrett_reduce
+/**
+ * Barrett reduction; given a 16-bit integer a, computes the centered
+ * representative congruent to a mod MLKEM_Q in [-(MLKEM_Q-1)/2, (MLKEM_Q-1)/2].
  *
- * Description: Barrett reduction; given a 16-bit integer a, computes
- *              centered representative congruent to a mod q in
- *              {-(q-1)/2,...,(q-1)/2}
+ * @reference{`barrett_reduce()` in the reference implementation @[REF].}
  *
- * Arguments:   - int16_t a: input integer to be reduced
+ * @param a Input integer to be reduced.
  *
- * Returns:     integer in {-(q-1)/2,...,(q-1)/2} congruent to a modulo q.
- *
- **************************************************/
-
-/* Reference: `barrett_reduce()` in the reference implementation @[REF]. */
+ * @return Integer in [-(MLKEM_Q-1)/2, (MLKEM_Q-1)/2] congruent to @p a modulo
+ *         MLKEM_Q.
+ */
 static MLK_INLINE int16_t mlk_barrett_reduce(int16_t a)
 __contract__(
   ensures(return_value > -MLKEM_Q_HALF && return_value < MLKEM_Q_HALF)
@@ -125,7 +118,8 @@ __contract__(
   for (i = 0; i < MLKEM_N; i++)
   __loop__(
     invariant(i <= MLKEM_N)
-    invariant(array_abs_bound(r->coeffs, 0, i, MLKEM_Q)))
+    invariant(array_abs_bound(r->coeffs, 0, i, MLKEM_Q))
+    decreases(MLKEM_N - i))
   {
     r->coeffs[i] = mlk_fqmul(r->coeffs[i], f);
   }
@@ -149,21 +143,20 @@ void mlk_poly_tomont(mlk_poly *r)
   mlk_poly_tomont_c(r);
 }
 
-/************************************************************
- * Name: mlk_scalar_signed_to_unsigned_q
+/**
+ * Constant-time conversion of signed representatives modulo MLKEM_Q within
+ * range [-(MLKEM_Q-1), MLKEM_Q-1] into unsigned representatives within
+ * range [0, MLKEM_Q-1].
  *
- * Description: Constant-time conversion of signed representatives
- *              modulo MLKEM_Q within range (-(MLKEM_Q-1) .. (MLKEM_Q-1))
- *              into unsigned representatives within range (0..(MLKEM_Q-1)).
+ * @reference{Not present in the reference implementation @[REF]. Used here
+ * to implement different semantics of `poly_reduce()`; see below. In the
+ * reference implementation @[REF] this logic is part of all compression
+ * functions (see `compress.c`).}
  *
- * Arguments: c: signed coefficient to be converted
+ * @param c Signed coefficient to be converted.
  *
- ************************************************************/
-
-/* Reference: Not present in the reference implementation @[REF].
- *            - Used here to implement different semantics of `poly_reduce()`;
- *              see below. in the reference implementation @[REF], this logic is
- *              part of all compression functions (see `compress.c`). */
+ * @return Unsigned representative in [0, MLKEM_Q).
+ */
 static MLK_INLINE int16_t mlk_scalar_signed_to_unsigned_q(int16_t c)
 __contract__(
   requires(c > -MLKEM_Q && c < MLKEM_Q)
@@ -201,7 +194,8 @@ __contract__(
   for (i = 0; i < MLKEM_N; i++)
   __loop__(
     invariant(i <= MLKEM_N)
-    invariant(array_bound(r->coeffs, 0, i, 0, MLKEM_Q)))
+    invariant(array_bound(r->coeffs, 0, i, 0, MLKEM_Q))
+    decreases(MLKEM_N - i))
   {
     /* Barrett reduction, giving signed canonical representative */
     int16_t t = mlk_barrett_reduce(r->coeffs[i]);
@@ -239,7 +233,8 @@ void mlk_poly_add(mlk_poly *r, const mlk_poly *b)
   __loop__(
     invariant(i <= MLKEM_N)
     invariant(forall(k0, i, MLKEM_N, r->coeffs[k0] == loop_entry(*r).coeffs[k0]))
-    invariant(forall(k1, 0, i, r->coeffs[k1] == loop_entry(*r).coeffs[k1] + b->coeffs[k1])))
+    invariant(forall(k1, 0, i, r->coeffs[k1] == loop_entry(*r).coeffs[k1] + b->coeffs[k1]))
+    decreases(MLKEM_N - i))
   {
     /* The preconditions imply that the addition stays within int16_t. */
     r->coeffs[i] = (int16_t)(r->coeffs[i] + b->coeffs[i]);
@@ -257,7 +252,8 @@ void mlk_poly_sub(mlk_poly *r, const mlk_poly *b)
   __loop__(
     invariant(i <= MLKEM_N)
     invariant(forall(k0, i, MLKEM_N, r->coeffs[k0] == loop_entry(*r).coeffs[k0]))
-    invariant(forall(k1, 0, i, r->coeffs[k1] == loop_entry(*r).coeffs[k1] - b->coeffs[k1])))
+    invariant(forall(k1, 0, i, r->coeffs[k1] == loop_entry(*r).coeffs[k1] - b->coeffs[k1]))
+    decreases(MLKEM_N - i))
   {
     /* The preconditions imply that the subtraction stays within int16_t. */
     r->coeffs[i] = (int16_t)(r->coeffs[i] - b->coeffs[i]);
@@ -282,7 +278,8 @@ __contract__(
   for (i = 0; i < MLKEM_N / 4; i++)
   __loop__(
     invariant(i <= MLKEM_N / 4)
-    invariant(array_abs_bound(x->coeffs, 0, 2 * i, MLKEM_Q)))
+    invariant(array_abs_bound(x->coeffs, 0, 2 * i, MLKEM_Q))
+    decreases(MLKEM_N / 4 - i))
   {
     x->coeffs[2 * i + 0] = mlk_fqmul(a->coeffs[4 * i + 1], mlk_zetas[64 + i]);
     /* The values in zeta table are <= MLKEM_Q in absolute value,
@@ -371,7 +368,8 @@ __contract__(
     invariant(array_abs_bound(r, 0,           j,           bound + MLKEM_Q))
     invariant(array_abs_bound(r, j,           start + len, bound))
     invariant(array_abs_bound(r, start + len, j + len,     bound + MLKEM_Q))
-    invariant(array_abs_bound(r, j + len,     MLKEM_N,     bound)))
+    invariant(array_abs_bound(r, j + len,     MLKEM_N,     bound))
+    decreases(start + len - j))
   {
     int16_t t;
     t = mlk_fqmul(r[j + len], zeta);
@@ -406,7 +404,8 @@ __contract__(
     invariant(start < MLKEM_N + 2 * len)
     invariant(k <= MLKEM_N / 2 && 2 * len * k == start + MLKEM_N)
     invariant(array_abs_bound(r, 0, start, layer * MLKEM_Q + MLKEM_Q))
-    invariant(array_abs_bound(r, start, MLKEM_N, layer * MLKEM_Q)))
+    invariant(array_abs_bound(r, start, MLKEM_N, layer * MLKEM_Q))
+    decreases(MLKEM_N - start))
   {
     int16_t zeta = mlk_zetas[k++];
     mlk_ntt_butterfly_block(r, zeta, start, len, layer * MLKEM_Q);
@@ -443,7 +442,8 @@ __contract__(
   for (layer = 1; layer <= 7; layer++)
   __loop__(
     invariant(1 <= layer && layer <= 8)
-    invariant(array_abs_bound(r, 0, MLKEM_N, layer * MLKEM_Q)))
+    invariant(array_abs_bound(r, 0, MLKEM_N, layer * MLKEM_Q))
+    decreases(8 - layer))
   {
     mlk_ntt_layer(r, layer);
   }
@@ -453,20 +453,20 @@ __contract__(
 }
 
 MLK_INTERNAL_API
-void mlk_poly_ntt(mlk_poly *p)
+void mlk_poly_ntt(mlk_poly *r)
 {
 #if defined(MLK_USE_NATIVE_NTT)
   int ret;
-  mlk_assert_abs_bound(p, MLKEM_N, MLKEM_Q);
-  ret = mlk_ntt_native(p->coeffs);
+  mlk_assert_abs_bound(r, MLKEM_N, MLKEM_Q);
+  ret = mlk_ntt_native(r->coeffs);
   if (ret == MLK_NATIVE_FUNC_SUCCESS)
   {
-    mlk_assert_abs_bound(p, MLKEM_N, MLK_NTT_BOUND);
+    mlk_assert_abs_bound(r, MLKEM_N, MLK_NTT_BOUND);
     return;
   }
 #endif /* MLK_USE_NATIVE_NTT */
 
-  mlk_poly_ntt_c(p);
+  mlk_poly_ntt_c(r);
 }
 
 
@@ -489,7 +489,8 @@ __contract__(
     invariant(array_abs_bound(r, 0, MLKEM_N, MLKEM_Q))
     invariant(start <= MLKEM_N && k <= 127)
     /* Normalised form of k == MLKEM_N / len - 1 - start / (2 * len) */
-    invariant(2 * len * k + start == 2 * MLKEM_N - 2 * len))
+    invariant(2 * len * k + start == 2 * MLKEM_N - 2 * len)
+    decreases(MLKEM_N - start))
   {
     unsigned j;
     int16_t zeta = mlk_zetas[k--];
@@ -497,7 +498,8 @@ __contract__(
     __loop__(
       invariant(start <= j && j <= start + len)
       invariant(start <= MLKEM_N && k <= 127)
-      invariant(array_abs_bound(r, 0, MLKEM_N, MLKEM_Q)))
+      invariant(array_abs_bound(r, 0, MLKEM_N, MLKEM_Q))
+      decreases(start + len - j))
     {
       int16_t t = r[j];
       /* The preconditions imply that the arithmetic does not overflow. */
@@ -532,7 +534,8 @@ __contract__(
   for (j = 0; j < MLKEM_N; j++)
   __loop__(
     invariant(j <= MLKEM_N)
-    invariant(array_abs_bound(r, 0, j, MLKEM_Q)))
+    invariant(array_abs_bound(r, 0, j, MLKEM_Q))
+    decreases(MLKEM_N - j))
   {
     r[j] = mlk_fqmul(r[j], f);
   }
@@ -541,7 +544,8 @@ __contract__(
   for (layer = 7; layer > 0; layer--)
   __loop__(
     invariant(0 <= layer && layer < 8)
-    invariant(array_abs_bound(r, 0, MLKEM_N, MLKEM_Q)))
+    invariant(array_abs_bound(r, 0, MLKEM_N, MLKEM_Q))
+    decreases(layer))
   {
     mlk_invntt_layer(r, layer);
   }
@@ -550,19 +554,19 @@ __contract__(
 }
 
 MLK_INTERNAL_API
-void mlk_poly_invntt_tomont(mlk_poly *p)
+void mlk_poly_invntt_tomont(mlk_poly *r)
 {
 #if defined(MLK_USE_NATIVE_INTT)
   int ret;
-  ret = mlk_intt_native(p->coeffs);
+  ret = mlk_intt_native(r->coeffs);
   if (ret == MLK_NATIVE_FUNC_SUCCESS)
   {
-    mlk_assert_abs_bound(p, MLKEM_N, MLK_INVNTT_BOUND);
+    mlk_assert_abs_bound(r, MLKEM_N, MLK_INVNTT_BOUND);
     return;
   }
 #endif /* MLK_USE_NATIVE_INTT */
 
-  mlk_poly_invntt_tomont_c(p);
+  mlk_poly_invntt_tomont_c(r);
 }
 
 #else /* !MLK_CONFIG_MULTILEVEL_NO_SHARED */

data/ext/pqcrypto/vendor/mlkem-native/mlkem/src/poly.h

@@ -27,37 +27,34 @@
 /* Absolute exclusive upper bound for the output of the forward NTT */
 #define MLK_NTT_BOUND (8 * MLKEM_Q)
 
-/*
- * Elements of R_q = Z_q[X]/(X^n + 1). Represents polynomial
- * coeffs[0] + X*coeffs[1] + X^2*coeffs[2] + ... + X^{n-1}*coeffs[n-1]
+/**
+ * Element of R_q = Z_q[X]/(X^n + 1). Represents polynomial
+ * coeffs[0] + X*coeffs[1] + X^2*coeffs[2] + ... + X^{n-1}*coeffs[n-1].
  */
 typedef struct
 {
-  int16_t coeffs[MLKEM_N];
+  int16_t coeffs[MLKEM_N]; /**< Polynomial coefficients. */
 } MLK_ALIGN mlk_poly;
 
-/*
- * INTERNAL presentation of precomputed data speeding up
+/**
+ * INTERNAL representation of precomputed data speeding up
  * the base multiplication of two polynomials in NTT domain.
  */
 typedef struct
 {
-  int16_t coeffs[MLKEM_N >> 1];
+  int16_t coeffs[MLKEM_N >> 1]; /**< Cached coefficients. */
 } MLK_ALIGN mlk_poly_mulcache;
 
-/*************************************************
- * Name:        mlk_montgomery_reduce
- *
- * Description: Generic Montgomery reduction; given a 32-bit integer a, computes
- *              16-bit integer congruent to a * R^-1 mod q, where R=2^16
- *
- * Arguments:   - int32_t a: input integer to be reduced, of absolute value
- *                smaller or equal to INT32_MAX - 2^15 * MLKEM_Q.
+/**
+ * Generic Montgomery reduction; given a 32-bit integer a, computes a 16-bit
+ * integer congruent to a * R^-1 mod MLKEM_Q, where R=2^16.
  *
- * Returns:     integer congruent to a * R^-1 modulo q, with absolute value
- *                <= ceil(|a| / 2^16) + (MLKEM_Q + 1)/2
+ * @param a Input integer to be reduced, of absolute value smaller or equal
+ *          to INT32_MAX - 2^15 * MLKEM_Q.
  *
- **************************************************/
+ * @return Integer congruent to a * R^-1 modulo MLKEM_Q, with absolute value
+ *         <= ceil(|a| / 2^16) + (MLKEM_Q + 1)/2.
+ */
 static MLK_ALWAYS_INLINE int16_t mlk_montgomery_reduce(int32_t a)
 __contract__(
     requires(a < +(INT32_MAX - (((int32_t)1 << 15) * MLKEM_Q)) &&
@@ -103,21 +100,18 @@ __contract__(
 }
 
 #define mlk_poly_tomont MLK_NAMESPACE(poly_tomont)
-/*************************************************
- * Name:        mlk_poly_tomont
- *
- * Description: Inplace conversion of all coefficients of a polynomial
- *              from normal domain to Montgomery domain
- *
- *              Bounds: Output < q in absolute value.
+/**
+ * In-place conversion of all coefficients of a polynomial from the normal
+ * domain to the Montgomery domain.
  *
- * Arguments:   - mlk_poly *r: pointer to input/output polynomial
+ * Bounds: output < MLKEM_Q in absolute value.
  *
- * Specification: Internal normalization required in `mlk_indcpa_keypair_derand`
- *                as part of matrix-vector multiplication
- *                @[FIPS203, Algorithm 13, K-PKE.KeyGen, L18].
+ * @spec{Internal normalization required in `mlk_indcpa_keypair_derand` as
+ * part of matrix-vector multiplication @[FIPS203, Algorithm 13, K-PKE.KeyGen,
+ * L18].}
  *
- **************************************************/
+ * @param[in,out] r Input/output polynomial.
+ */
 MLK_INTERNAL_API
 void mlk_poly_tomont(mlk_poly *r)
 __contract__(
@@ -127,27 +121,23 @@ __contract__(
 );
 
 #define mlk_poly_mulcache_compute MLK_NAMESPACE(poly_mulcache_compute)
-/************************************************************
- * Name: mlk_poly_mulcache_compute
- *
- * Description: Computes the mulcache for a polynomial in NTT domain
- *
- *              The mulcache of a degree-2 polynomial b := b0 + b1*X
- *              in Fq[X]/(X^2-zeta) is the value b1*zeta, needed when
- *              computing products of b in Fq[X]/(X^2-zeta).
+/**
+ * Compute the mulcache for a polynomial in NTT domain.
  *
- *              The mulcache of a polynomial in NTT domain -- which is
- *              a 128-tuple of degree-2 polynomials in Fq[X]/(X^2-zeta),
- *              for varying zeta, is the 128-tuple of mulcaches of those
- *              polynomials.
+ * The mulcache of a degree-2 polynomial b := b0 + b1*X in Fq[X]/(X^2-zeta)
+ * is the value b1*zeta, needed when computing products of b in
+ * Fq[X]/(X^2-zeta).
  *
- * Arguments: - x: Pointer to mulcache to be populated
- *            - a: Pointer to input polynomial
+ * The mulcache of a polynomial in NTT domain -- which is a 128-tuple of
+ * degree-2 polynomials in Fq[X]/(X^2-zeta), for varying zeta, is the
+ * 128-tuple of mulcaches of those polynomials.
  *
- * Specification:
- * - Caches `b_1 * \gamma` in @[FIPS203, Algorithm 12, BaseCaseMultiply, L1]
+ * @spec{Caches `b_1 * \gamma` in @[FIPS203, Algorithm 12, BaseCaseMultiply,
+ * L1].}
  *
- ************************************************************/
+ * @param[out] x Mulcache to be populated.
+ * @param[in]  a Input polynomial.
+ */
 /*
  * NOTE: The default C implementation of this function populates
  * the mulcache with values in (-q,q), but this is not needed for the
@@ -162,21 +152,17 @@ __contract__(
 );
 
 #define mlk_poly_reduce MLK_NAMESPACE(poly_reduce)
-/*************************************************
- * Name:        mlk_poly_reduce
- *
- * Description: Converts polynomial to _unsigned canonical_ representatives.
- *
- *              The input coefficients can be arbitrary integers in int16_t.
- *              The output coefficients are in [0,1,...,MLKEM_Q-1].
+/**
+ * Convert a polynomial to unsigned canonical representatives.
  *
- * Arguments:   - mlk_poly *r: pointer to input/output polynomial
+ * The input coefficients can be arbitrary integers in int16_t. The output
+ * coefficients are in [0,1,..,MLKEM_Q-1].
  *
- * Specification: Normalizes on unsigned canoncial representatives
- *                ahead of calling @[FIPS203, Compress_d, Eq (4.7)].
- *                This is not made explicit in FIPS 203.
+ * @spec{Normalizes on unsigned canonical representatives ahead of calling
+ * @[FIPS203, Compress_d, Eq (4.7)]. This is not made explicit in FIPS 203.}
  *
- **************************************************/
+ * @param[in,out] r Input/output polynomial.
+ */
 /*
  * NOTE: The semantics of mlk_poly_reduce() is different in
  * the reference implementation, which requires
@@ -193,23 +179,19 @@ __contract__(
 );
 
 #define mlk_poly_add MLK_NAMESPACE(poly_add)
-/************************************************************
- * Name: mlk_poly_add
- *
- * Description: Adds two polynomials in place
+/**
+ * Add two polynomials in place.
  *
- * Arguments: - r: Pointer to input-output polynomial to be added to.
- *            - b: Pointer to input polynomial that should be added
- *                 to r. Must be disjoint from r.
+ * The coefficients of @p r and @p b must be such that the addition does not
+ * overflow. Otherwise, the behaviour of this function is undefined.
  *
- * The coefficients of r and b must be so that the addition does
- * not overflow. Otherwise, the behaviour of this function is undefined.
+ * @spec{@[FIPS203, 2.4.5, Arithmetic With Polynomials and NTT
+ * Representations]. Used in @[FIPS203, Algorithm 14 (K-PKE.Encrypt), L21].}
  *
- * Specification:
- * - @[FIPS203, 2.4.5, Arithmetic With Polynomials and NTT Representations]
- * - Used in @[FIPS203, Algorithm 14 (K-PKE.Encrypt), L21]
- *
- ************************************************************/
+ * @param[in,out] r Input-output polynomial to be added to.
+ * @param[in]     b Input polynomial that should be added to @p r. Must be
+ *                  disjoint from @p r.
+ */
 /*
  * NOTE: The reference implementation uses a 3-argument mlk_poly_add.
  * We specialize to the accumulator form to avoid reasoning about aliasing.
@@ -226,19 +208,15 @@ __contract__(
 );
 
 #define mlk_poly_sub MLK_NAMESPACE(poly_sub)
-/*************************************************
- * Name:        mlk_poly_sub
+/**
+ * Subtract two polynomials; no modular reduction is performed.
  *
- * Description: Subtract two polynomials; no modular reduction is performed
+ * @spec{@[FIPS203, 2.4.5, Arithmetic With Polynomials and NTT
+ * Representations]. Used in @[FIPS203, Algorithm 15, K-PKE.Decrypt, L6].}
  *
- * Arguments: - mlk_poly *r: Pointer to input-output polynomial to be added to.
- *            - const mlk_poly *b: Pointer to second input polynomial
- *
- * Specification:
- * - @[FIPS203, 2.4.5, Arithmetic With Polynomials and NTT Representations]
- * - Used in @[FIPS203, Algorithm 15, K-PKE.Decrypt, L6]
- *
- **************************************************/
+ * @param[in,out] r Input-output polynomial to be subtracted from.
+ * @param[in]     b Second input polynomial.
+ */
 /*
  * NOTE: The reference implementation uses a 3-argument mlk_poly_sub.
  * We specialize to the accumulator form to avoid reasoning about aliasing.
@@ -255,26 +233,24 @@ __contract__(
 );
 
 #define mlk_poly_ntt MLK_NAMESPACE(poly_ntt)
-/*************************************************
- * Name:        mlk_poly_ntt
+/**
+ * Compute the negacyclic number-theoretic transform (NTT) of a polynomial
+ * in place.
  *
- * Description: Computes negacyclic number-theoretic transform (NTT) of
- *              a polynomial in place.
+ * The input is assumed to be in normal order and coefficient-wise bound by
+ * MLKEM_Q in absolute value.
  *
- *              The input is assumed to be in normal order and
- *              coefficient-wise bound by MLKEM_Q in absolute value.
+ * The output polynomial is in bitreversed order, or of a custom order if
+ * MLK_USE_NATIVE_NTT_CUSTOM_ORDER is set, and coefficient-wise bound
+ * by MLK_NTT_BOUND in absolute value.
  *
- *              The output polynomial is in bitreversed order, and
- *              coefficient-wise bound by MLK_NTT_BOUND in absolute value.
+ * (NOTE: Sometimes the input to the NTT is actually smaller, which gives
+ * better bounds.)
  *
- *              (NOTE: Sometimes the input to the NTT is actually smaller,
- *               which gives better bounds.)
+ * @spec{Implements @[FIPS203, Algorithm 9, NTT].}
  *
- * Arguments:   - mlk_poly *p: pointer to in/output polynomial
- *
- * Specification: Implements @[FIPS203, Algorithm 9, NTT]
- *
- **************************************************/
+ * @param[in,out] r Input/output polynomial.
+ */
 MLK_INTERNAL_API
 void mlk_poly_ntt(mlk_poly *r)
 __contract__(
@@ -285,27 +261,24 @@ __contract__(
 );
 
 #define mlk_poly_invntt_tomont MLK_NAMESPACE(poly_invntt_tomont)
-/*************************************************
- * Name:        mlk_poly_invntt_tomont
+/**
+ * Compute the inverse negacyclic number-theoretic transform (NTT) of a
+ * polynomial in place; input assumed to be in bitreversed order, output in
+ * normal order.
  *
- * Description: Computes inverse of negacyclic number-theoretic transform (NTT)
- *              of a polynomial in place;
- *              inputs assumed to be in bitreversed order, output in normal
- *              order
+ * The input is assumed to be in bitreversed order, or of a custom order if
+ * MLK_USE_NATIVE_NTT_CUSTOM_ORDER is set, and can have arbitrary
+ * coefficients in int16_t.
  *
- *              The input is assumed to be in bitreversed order, and can
- *              have arbitrary coefficients in int16_t.
+ * The output polynomial is in normal order, and coefficient-wise bound by
+ * MLK_INVNTT_BOUND in absolute value.
  *
- *              The output polynomial is in normal order, and
- *              coefficient-wise bound by MLK_INVNTT_BOUND in absolute value.
+ * @spec{Implements composition of @[FIPS203, Algorithm 10, NTT^{-1}] and
+ * elementwise modular multiplication with a suitable Montgomery factor
+ * introduced during the base multiplication.}
  *
- * Arguments:   - uint16_t *a: pointer to in/output polynomial
- *
- * Specification: Implements composition of @[FIPS203, Algorithm 10, NTT^{-1}]
- *                and elementwise modular multiplication with a suitable
- *                Montgomery factor introduced during the base multiplication.
- *
- **************************************************/
+ * @param[in,out] r Input/output polynomial.
+ */
 MLK_INTERNAL_API
 void mlk_poly_invntt_tomont(mlk_poly *r)
 __contract__(