The beginnings of documentation, yay

.gitignore

@@ -7,6 +7,7 @@
 *.out
 *.log
 tmp/
+doc/
 inc/blst.h
 inc/blst_aux.h
 .vscode/

README.md

@@ -11,7 +11,7 @@ Done so far:
   - Polynomial multi commitment and verification
   - [FK20](https://github.com/khovratovich/Kate/blob/master/Kate_amortized.pdf) single proof method (needs a tidy up)
 
-## Installation
+## Install
 
 Build the [Blst library](https://github.com/supranational/blst) following the instructions there. Then,
 
@@ -83,9 +83,20 @@ make fk20_proofs_test_debug
 
 This magic is implemented via the `ASSERT` macro in _c_kzg.h_.
 
+## Make documentation
+
+I've just started inserting `doxygen` style documentation in a few files, and will aim for total coverage eventually. Build the docs in the top directory as follows:
+
+```
+doxygen Doxyfile
+```
+
+This will produce a _doc/html_ directory. Visit the _doc/html/index.html_ file in a browser to view the documentation.
+
 ## Prerequisites
 
  - Blst library (see above)
  - `clang` compiler. I'm using Clang 10.0.0. I'll likely add `gcc` options in future.
  - The Makefile is GNU make compatible.
  - I'm developing on Ubuntu 20.04. Will check portability later.
+ - [Doxygen](https://www.doxygen.nl/index.html) for building the documentation. I'm using v1.8.17 right now.

src/blst_util.c

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file blst_util.c */
+
 #include "blst_util.h"
 #include "debug_util.h"
 

src/blst_util.h

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file blst_util.h */
+
 #include "c_kzg.h"
 
 static const blst_fr fr_zero = {0L, 0L, 0L, 0L};

src/c_kzg.h

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file c_kzg_util.c */
+
 #ifndef C_KZG_H
 #define C_KZG_H
 

src/c_kzg_util.c

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file c_kzg_util.c */
+
 #include <stdlib.h> // malloc
 #include "c_kzg_util.h"
 

src/c_kzg_util.h

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file c_kzg_util.c */
+
 #include "c_kzg.h"
 
 C_KZG_RET c_kzg_malloc(void **p, size_t n);

src/fft_common.c

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file fft_common.c */
+
 #include <stdlib.h> // free()
 #include "fft_common.h"
 #include "blst_util.h"

src/fft_common.h

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file fft_common.h */
+
 #ifndef FFT_COMMON
 #define FFT_COMMON
 

src/fft_fr.c

@@ -14,18 +14,40 @@
  * limitations under the License.
  */
 
+/**
+ * @file fft_fr.c
+ *
+ * Discrete fourier transforms over arrays of field elements.
+ *
+ * Also known as [number theoretic
+ * transforms](https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform).
+ *
+ * @remark Functions here work only for lengths that are a power of two.
+ */
+
 #include "fft_fr.h"
 #include "blst_util.h"
 
-// Slow Fourier Transform (simple, good for small sizes)
+/**
+ * Slow Fourier Transform.
+ *
+ * This is simple, and ok for small sizes. It's mostly useful for testing.
+ *
+ * @param[out] out    The results (array of length @p n)
+ * @param[in]  in     The input data (array of length @p n * @p stride)
+ * @param[in]  stride The input data stride
+ * @param[in]  roots  Roots of unity (array of length @p n * @p roots_stride)
+ * @param[in]  roots_stride The stride interval among the roots of unity
+ * @param[in]  n      Length of the FFT, must be a power of two
+ */
 void fft_fr_slow(blst_fr *out, const blst_fr *in, uint64_t stride, const blst_fr *roots, uint64_t roots_stride,
-                 uint64_t l) {
+                 uint64_t n) {
     blst_fr v, last, jv, r;
-    for (uint64_t i = 0; i < l; i++) {
+    for (uint64_t i = 0; i < n; i++) {
         blst_fr_mul(&last, &in[0], &roots[0]);
-        for (uint64_t j = 1; j < l; j++) {
+        for (uint64_t j = 1; j < n; j++) {
             jv = in[j * stride];
-            r = roots[((i * j) % l) * roots_stride];
+            r = roots[((i * j) % n) * roots_stride];
             blst_fr_mul(&v, &jv, &r);
             blst_fr_add(&last, &last, &v);
         }
@@ -33,10 +55,21 @@ void fft_fr_slow(blst_fr *out, const blst_fr *in, uint64_t stride, const blst_fr
     }
 }
 
-// Fast Fourier Transform
+/**
+ * Fast Fourier Transform.
+ *
+ * Recursively divide and conquer.
+ *
+ * @param[out] out    The results (array of length @p n)
+ * @param[in]  in     The input data (array of length @p n * @p stride)
+ * @param[in]  stride The input data stride
+ * @param[in]  roots  Roots of unity (array of length @p n * @p roots_stride)
+ * @param[in]  roots_stride The stride interval among the roots of unity
+ * @param[in]  n      Length of the FFT, must be a power of two
+ */
 void fft_fr_fast(blst_fr *out, const blst_fr *in, uint64_t stride, const blst_fr *roots, uint64_t roots_stride,
-                 uint64_t l) {
-    uint64_t half = l / 2;
+                 uint64_t n) {
+    uint64_t half = n / 2;
     if (half > 0) { // Tunable parameter
         fft_fr_fast(out, in, stride * 2, roots, roots_stride * 2, half);
         fft_fr_fast(out + half, in + stride, stride * 2, roots, roots_stride * 2, half);
@@ -47,16 +80,26 @@ void fft_fr_fast(blst_fr *out, const blst_fr *in, uint64_t stride, const blst_fr
             blst_fr_add(&out[i], &out[i], &y_times_root);
         }
     } else {
-        fft_fr_slow(out, in, stride, roots, roots_stride, l);
+        fft_fr_slow(out, in, stride, roots, roots_stride, n);
     }
 }
 
-// The main entry point for forward and reverse FFTs
-C_KZG_RET fft_fr(blst_fr *out, const blst_fr *in, bool inv, uint64_t n, const FFTSettings *fs) {
+/**
+ * The main entry point for forward and reverse FFTs over the finite field.
+ *
+ * @param[out] out     The results (array of length @p n)
+ * @param[in]  in      The input data (array of length @p n)
+ * @param[in]  inverse `false` for forward transform, `true` for inverse transform
+ * @param[in]  n       Length of the FFT, must be a power of two
+ * @param[in]  fs      Pointer to previously initialised FFTSettings structure with `max_width` at least @p n.
+ * @retval C_CZK_OK      All is well
+ * @retval C_CZK_BADARGS Invalid parameters were supplied
+ */
+C_KZG_RET fft_fr(blst_fr *out, const blst_fr *in, bool inverse, uint64_t n, const FFTSettings *fs) {
     uint64_t stride = fs->max_width / n;
     ASSERT(n <= fs->max_width, C_KZG_BADARGS);
     ASSERT(is_power_of_two(n), C_KZG_BADARGS);
-    if (inv) {
+    if (inverse) {
         blst_fr inv_len;
         fr_from_uint64(&inv_len, n);
         blst_fr_eucl_inverse(&inv_len, &inv_len);

src/fft_fr.h

@@ -14,7 +14,8 @@
  * limitations under the License.
  */
 
-#include "c_kzg.h"
+/** @file fft_fr.h */
+
 #include "fft_common.h"
 
 void fft_fr_slow(blst_fr *out, const blst_fr *in, uint64_t stride, const blst_fr *roots, uint64_t roots_stride,

src/fft_g1.c

@@ -14,19 +14,41 @@
  * limitations under the License.
  */
 
+/**
+ * @file fft_g1.c
+ *
+ * Discrete fourier transforms over arrays of G1 group elements.
+ *
+ * Also known as [number theoretic
+ * transforms](https://en.wikipedia.org/wiki/Discrete_Fourier_transform_(general)#Number-theoretic_transform).
+ *
+ * @remark Functions here work only for lengths that are a power of two.
+ */
+
 #include "fft_g1.h"
 #include "blst_util.h"
 
-// Slow Fourier Transform (simple, good for small sizes)
+/**
+ * Slow Fourier Transform.
+ *
+ * This is simple, and ok for small sizes. It's mostly useful for testing.
+ *
+ * @param[out] out    The results (array of length @p n)
+ * @param[in]  in     The input data (array of length @p n * @p stride)
+ * @param[in]  stride The input data stride
+ * @param[in]  roots  Roots of unity (array of length @p n * @p roots_stride)
+ * @param[in]  roots_stride The stride interval among the roots of unity
+ * @param[in]  n      Length of the FFT, must be a power of two
+ */
 void fft_g1_slow(blst_p1 *out, const blst_p1 *in, uint64_t stride, const blst_fr *roots, uint64_t roots_stride,
-                 uint64_t l) {
+                 uint64_t n) {
     blst_p1 v, last, jv;
     blst_fr r;
-    for (uint64_t i = 0; i < l; i++) {
+    for (uint64_t i = 0; i < n; i++) {
         p1_mul(&last, &in[0], &roots[0]);
-        for (uint64_t j = 1; j < l; j++) {
+        for (uint64_t j = 1; j < n; j++) {
             jv = in[j * stride];
-            r = roots[((i * j) % l) * roots_stride];
+            r = roots[((i * j) % n) * roots_stride];
             p1_mul(&v, &jv, &r);
             blst_p1_add_or_double(&last, &last, &v);
         }
@@ -34,10 +56,21 @@ void fft_g1_slow(blst_p1 *out, const blst_p1 *in, uint64_t stride, const blst_fr
     }
 }
 
-// Fast Fourier Transform
+/**
+ * Fast Fourier Transform.
+ *
+ * Recursively divide and conquer.
+ *
+ * @param[out] out    The results (array of length @p n)
+ * @param[in]  in     The input data (array of length @p n * @p stride)
+ * @param[in]  stride The input data stride
+ * @param[in]  roots  Roots of unity (array of length @p n * @p roots_stride)
+ * @param[in]  roots_stride The stride interval among the roots of unity
+ * @param[in]  n      Length of the FFT, must be a power of two
+ */
 void fft_g1_fast(blst_p1 *out, const blst_p1 *in, uint64_t stride, const blst_fr *roots, uint64_t roots_stride,
-                 uint64_t l) {
-    uint64_t half = l / 2;
+                 uint64_t n) {
+    uint64_t half = n / 2;
     if (half > 0) { // Tunable parameter
         fft_g1_fast(out, in, stride * 2, roots, roots_stride * 2, half);
         fft_g1_fast(out + half, in + stride, stride * 2, roots, roots_stride * 2, half);
@@ -48,11 +81,21 @@ void fft_g1_fast(blst_p1 *out, const blst_p1 *in, uint64_t stride, const blst_fr
             blst_p1_add_or_double(&out[i], &out[i], &y_times_root);
         }
     } else {
-        fft_g1_slow(out, in, stride, roots, roots_stride, l);
+        fft_g1_slow(out, in, stride, roots, roots_stride, n);
     }
 }
 
-// The main entry point for forward and reverse FFTs
+/**
+ * The main entry point for forward and reverse FFTs over the finite field.
+ *
+ * @param[out] out     The results (array of length @p n)
+ * @param[in]  in      The input data (array of length @p n)
+ * @param[in]  inverse `false` for forward transform, `true` for inverse transform
+ * @param[in]  n       Length of the FFT, must be a power of two
+ * @param[in]  fs      Pointer to previously initialised FFTSettings structure with `max_width` at least @p n.
+ * @retval C_CZK_OK      All is well
+ * @retval C_CZK_BADARGS Invalid parameters were supplied
+ */
 C_KZG_RET fft_g1(blst_p1 *out, const blst_p1 *in, bool inv, uint64_t n, const FFTSettings *fs) {
     uint64_t stride = fs->max_width / n;
     ASSERT(n <= fs->max_width, C_KZG_BADARGS);

src/fft_g1.h

@@ -14,7 +14,8 @@
  * limitations under the License.
  */
 
-#include "c_kzg.h"
+/** @file fft_g1.h */
+
 #include "fft_common.h"
 
 void fft_g1_slow(blst_p1 *out, const blst_p1 *in, uint64_t stride, const blst_fr *roots, uint64_t roots_stride,

src/fk20_proofs.c

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file fk20_proofs.c */
+
 // FK20 refers to this technique: https://github.com/khovratovich/Kate/blob/master/Kate_amortized.pdf
 
 #include <stdlib.h> // free()
@@ -177,6 +179,17 @@ C_KZG_RET da_using_fk20_single(blst_p1 *out, const poly *p, FK20SingleSettings *
     return C_KZG_OK;
 }
 
+/**
+ * Initialise settings for an FK20 single proof.
+ *
+ * free_fk20_single_settings must be called to deallocate this structure.
+ *
+ * @param fk[out] The initialised settings
+ * @param n2[in] The size
+ * @param ks[in] KZGSettings that have already been initialised
+ *
+ * @return C_KZG_RET
+ */
 C_KZG_RET new_fk20_single_settings(FK20SingleSettings *fk, uint64_t n2, KZGSettings *ks) {
     int n = n2 / 2;
     blst_p1 *x;

src/fk20_proofs.h

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file fk20_proofs.h */
+
 #include "c_kzg.h"
 #include "kzg_proofs.h"
 

src/kzg_proofs.c

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file kzg_proofs.c */
+
 #include <stddef.h> // NULL
 #include "kzg_proofs.h"
 

src/kzg_proofs.h

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file kzg_proofs.h */
+
 #include "c_kzg.h"
 #include "fft_fr.h"
 #include "poly.h"

src/poly.c

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file poly.c */
+
 #include <stdlib.h> // NULL, free()
 #include "c_kzg_util.h"
 #include "poly.h"

src/poly.h

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+/** @file poly.h */
+
 #include "c_kzg.h"
 #include "blst_util.h"