Document the new DPF surfaces in one command set, and test the field, half-tree, and multipoint edges.

Co-authored-by: Cursor <cursoragent@cursor.com>

include/grotto/nmod.hpp

@@ -28,16 +28,23 @@ namespace nmod_detail
 using u128 = unsigned __int128;
 }
 
+/// @brief Quotient and truncated fractional residue of one reduction.
 struct nmod_result
 {
-    /// `floor({x/M} * 2^residue_bits)`, in `[0, 2^residue_bits)`.
+    /// @brief `floor({x/M} * 2^residue_bits)`, in `[0, 2^residue_bits)`.
     std::int64_t residue = 0;
-    /// `floor(x/M)`.
+    /// @brief `floor(x/M)`.
     std::int64_t quotient = 0;
 };
 
-/// `x_raw / 2^x_bits` modulo `M`, with `1/M ≈ recip_raw / 2^recip_bits`.
-/// `recip_raw` is a positive magnitude of at most 128 bits.
+/// @brief `x_raw / 2^x_bits` modulo `M`, with `1/M ≈ recip_raw / 2^recip_bits`.
+/// @details `recip_raw` is a positive magnitude of at most 128 bits.
+/// @param x_raw the signed integer significand
+/// @param x_bits the fractional width of `x_raw`
+/// @param recip_raw the positive magnitude of the rounded reciprocal
+/// @param recip_bits the fractional width of `recip_raw`
+/// @param residue_bits the fractional bits kept in the residue
+/// @return `x_raw / 2^x_bits` modulo `M`, with `1/M ≈ recip_raw / 2^recip_bits`
 /// @throws std::invalid_argument if the reciprocal is zero or a width is illegal.
 /// @throws std::overflow_error if the quotient does not fit in `int64_t`.
 HEDLEY_WARN_UNUSED_RESULT
@@ -174,9 +181,14 @@ inline nmod_result nmod(std::int64_t x_raw, unsigned x_bits,
     return out;
 }
 
-/// Modulus `2^{-exp}` by an exact shift. Positive `exp` multiplies by
+/// @brief Modulus `2^{-exp}` by an exact shift. Positive `exp` multiplies by
 /// `2^exp` (`exp`'s `2^{-13}` split). Zero splits at the integer (`2^x`).
-/// Negative `exp` is a modulus above one.
+/// @details Negative `exp` is a modulus above one.
+/// @param x_raw the signed integer significand
+/// @param x_bits the fractional width of `x_raw`
+/// @param exp the power-of-two exponent
+/// @param residue_bits the fractional bits kept in the residue
+/// @return Modulus `2^{-exp}` by an exact shift
 /// @throws std::overflow_error if `exp` does not fit the reciprocal width.
 HEDLEY_WARN_UNUSED_RESULT
 inline nmod_result nmod_pow2(std::int64_t x_raw, unsigned x_bits, int exp,