Improve docs

src/c_kzg.h

@@ -34,7 +34,7 @@
 typedef enum {
     C_KZG_OK = 0,  /**< Success! */
     C_KZG_BADARGS, /**< The supplied data is invalid in some way */
-    C_KZG_ERROR,   /**< Internal error - this should never occur and indicates a bug in the library */
+    C_KZG_ERROR,   /**< Internal error - this should never occur and may indicate a bug in the library */
     C_KZG_MALLOC,  /**< Could not allocate memory */
 } C_KZG_RET;
 

src/fk20_proofs.c

@@ -197,7 +197,7 @@ C_KZG_RET toeplitz_part_3(blst_p1 *out, const blst_p1 *h_ext_fft, uint64_t n2, c
 /**
  * Reorder and extend polynomial coefficients for the toeplitz method.
  *
- * @warning Allocates space for the return polynomial that needs to be freed by calling #free_poly.
+ * @remark Allocates space for the return polynomial that needs to be freed by calling #free_poly.
  *
  * @param[out] out The reordered polynomial, size `n * 2`
  * @param[in]  in  The input polynomial, size `n`
@@ -226,6 +226,11 @@ C_KZG_RET toeplitz_coeffs_step(poly *out, const poly *in) {
  * The upper half of the polynomial coefficients is always 0, so we do not need to extend to twice the size
  * for Toeplitz matrix multiplication.
  *
+ * Simultaneously calculates all the KZG proofs for `x_i = w^i` (`0 <= i < 2n`), where `w` is a `(2 * n)`th root of
+ * unity. The `2n` comes from the polynomial being extended with zeros to twice the original size.
+ *
+ * `out[i]` is the proof for `y[i]`, the evaluation of the polynomial at `fs.expanded_roots_of_unity[i]`.
+ *
  * @param[out] out Array size `n * 2`
  * @param[in]  p   Polynomial, size `n`
  * @param[in]  fk  FK20 single settings previously initialised by #new_fk20_single_settings
@@ -233,8 +238,6 @@ C_KZG_RET toeplitz_coeffs_step(poly *out, const poly *in) {
  * @retval C_CZK_BADARGS Invalid parameters were supplied
  * @retval C_CZK_ERROR   An internal error occurred
  * @retval C_CZK_MALLOC  Memory allocation failed
- *
- * @todo Better parameter descriptions
  */
 C_KZG_RET fk20_single_da_opt(blst_p1 *out, const poly *p, FK20SingleSettings *fk) {
     uint64_t n = p->length, n2 = n * 2;
@@ -263,16 +266,20 @@ C_KZG_RET fk20_single_da_opt(blst_p1 *out, const poly *p, FK20SingleSettings *fk
 }
 
 /**
- * Data availability using FK20 single.
+ * Data availability using the FK20 single algorithm.
  *
- * @param[out] out Array size `n * 2`
+ * Simultaneously calculates all the KZG proofs for `x_i = w^i` (`0 <= i < 2n`), where `w` is a `(2 * n)`th root of
+ * unity. The `2n` comes from the polynomial being extended with zeros to twice the original size.
+ *
+ * `out[reverse_bits_limited(2 * n, i)]` is the proof for `y[i]`, the evaluation of the polynomial at
+ * `fs.expanded_roots_of_unity[i]`.
+ *
+ * @param[out] out All the proofs, array length 2 * `n`
  * @param[in]  p   Polynomial, size `n`
  * @param[in]  fk  FK20 single settings previously initialised by #new_fk20_single_settings
  * @retval C_CZK_OK      All is well
  * @retval C_CZK_BADARGS Invalid parameters were supplied
  * @retval C_CZK_ERROR   An internal error occurred
- *
- * @todo Better parameter descriptions
  */
 C_KZG_RET da_using_fk20_single(blst_p1 *out, const poly *p, FK20SingleSettings *fk) {
     uint64_t n = p->length, n2 = n * 2;

src/fk20_proofs_test.c

@@ -123,11 +123,15 @@ void fk_single(void) {
     TEST_CHECK(C_KZG_OK == new_kzg_settings(&ks, s1, s2, secrets_len, &fs));
     TEST_CHECK(C_KZG_OK == new_fk20_single_settings(&fk, 2 * poly_len, &ks));
 
-    // Generate the proofs
+    // Commit to the polynomial
     commit_to_poly(&commitment, &p, &ks);
+
+    // 1. First with `da_using_fk20_single`
+
+    // Generate the proofs
     TEST_CHECK(da_using_fk20_single(all_proofs, &p, &fk) == C_KZG_OK);
 
-    // Verify the proof at each position
+    // Verify the proof at each root of unity
     for (uint64_t i = 0; i < 2 * poly_len; i++) {
         x = fs.expanded_roots_of_unity[i];
         eval_poly(&y, &p, &x);
@@ -137,6 +141,21 @@ void fk_single(void) {
         TEST_CHECK(true == result);
     }
 
+    // 2. Exactly the same thing again with `fk20_single_da_opt`
+
+    // Generate the proofs
+    TEST_CHECK(fk20_single_da_opt(all_proofs, &p, &fk) == C_KZG_OK);
+
+    // Verify the proof at each root of unity
+    for (uint64_t i = 0; i < 2 * poly_len; i++) {
+        x = fs.expanded_roots_of_unity[i];
+        eval_poly(&y, &p, &x);
+        proof = all_proofs[i];
+
+        TEST_CHECK(C_KZG_OK == check_proof_single(&result, &commitment, &proof, &x, &y, &ks));
+        TEST_CHECK(true == result);
+    }
+
     // Clean up
     free_poly(&p);
     free_fft_settings(&fs);
@@ -178,11 +197,13 @@ void fk_single_strided(void) {
     TEST_CHECK(C_KZG_OK == new_kzg_settings(&ks, s1, s2, secrets_len, &fs));
     TEST_CHECK(C_KZG_OK == new_fk20_single_settings(&fk, 2 * poly_len, &ks));
 
-    // Generate the proofs
+    // Commit to the polynomial
     commit_to_poly(&commitment, &p, &ks);
+
+    // Generate the proofs
     TEST_CHECK(da_using_fk20_single(all_proofs, &p, &fk) == C_KZG_OK);
 
-    // Verify the proof at each position
+    // Verify the proof at each root of unity
     for (uint64_t i = 0; i < 2 * poly_len; i++) {
         x = fs.expanded_roots_of_unity[i * stride];
         eval_poly(&y, &p, &x);