From 25be720f620b5c54a6ec2d513a485fa3c3d20eb2 Mon Sep 17 00:00:00 2001
From: Ramana Kumar <ramana@member.fsf.org>
Date: Sun, 18 Sep 2022 09:51:55 +0100
Subject: [PATCH] Add some documentation

---
 src/kzg_proofs.c | 21 +++++++++++++++++++++
 src/poly.c       | 30 ++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/src/kzg_proofs.c b/src/kzg_proofs.c
index 5184e37..4b7d19f 100644
--- a/src/kzg_proofs.c
+++ b/src/kzg_proofs.c
@@ -43,6 +43,15 @@ C_KZG_RET commit_to_poly(g1_t *out, const poly *p, const KZGSettings *ks) {
     return C_KZG_OK;
 }
 
+/**
+ * Make a KZG commitment to a polynomial in Lagrange form.
+ *
+ * @param[out] out The commitment to the polynomial, in the form of a G1 group point
+ * @param[in]  p_l The polynomial to be committed to
+ * @param[in]  ks  The settings containing the secrets, previously initialised with #new_kzg_settings
+ * @retval C_CZK_OK      All is well
+ * @retval C_CZK_BADARGS Invalid parameters were supplied
+ */
 C_KZG_RET commit_to_poly_l(g1_t *out, const poly_l *p_l, const KZGSettings *ks) {
     CHECK(p_l->length <= ks->length);
     g1_linear_combination(out, ks->secret_g1_l, p_l->values, p_l->length);
@@ -91,6 +100,18 @@ C_KZG_RET check_proof_single(bool *out, const g1_t *commitment, const g1_t *proo
     return C_KZG_OK;
 }
 
+/**
+ * Compute KZG proof for evaluation of a polynomial in Lagrange form.
+ *
+ * @param[out] out The proof, in the form of a G1 point
+ * @param[in]  p   The polynomial
+ * @param[in]  x0  The x-value the polynomial is to be proved at
+ * @param[in]  y   The y-value of the polynomial evaluation, which is assumed to be correct
+ * @param[in]  ks  The settings containing the secrets, previously initialised with #new_kzg_settings
+ * @retval C_CZK_OK      All is well
+ * @retval C_CZK_ERROR   An internal error occurred
+ * @retval C_CZK_MALLOC  Memory allocation failed
+ */
 C_KZG_RET compute_proof_single_l(g1_t *out, const poly_l *p, const fr_t *x0, const fr_t *y, const KZGSettings *ks) {
   fr_t tmp, tmp2;
   poly_l q;
diff --git a/src/poly.c b/src/poly.c
index e952aae..9b10b95 100644
--- a/src/poly.c
+++ b/src/poly.c
@@ -584,6 +584,16 @@ C_KZG_RET new_poly(poly *out, uint64_t length) {
     return new_fr_array(&out->coeffs, length);
 }
 
+/**
+ * Initialise an empty polynomial in Lagrange form of the given size.
+ *
+ * @remark This allocates space for the Lagrange values that must be later reclaimed by calling #free_poly_l.
+ *
+ * @param[out] out    The initialised polynomial structure
+ * @param[in]  length The number of coefficients required, which is one more than the polynomial's degree
+ * @retval C_CZK_OK      All is well
+ * @retval C_CZK_MALLOC  Memory allocation failed
+ */
 C_KZG_RET new_poly_l(poly_l *out, uint64_t length) {
     out->length = length;
     return new_fr_array(&out->values, length);
@@ -610,6 +620,18 @@ C_KZG_RET new_poly_with_coeffs(poly *out, const fr_t *coeffs, uint64_t length) {
     return C_KZG_OK;
 }
 
+/**
+ * Initialise a polynomial in Lagrange form from the given polynomial in coefficient form.
+ *
+ * @remark This allocates space for the Lagrange values that must be later reclaimed by calling #free_poly_l.
+ *
+ * @param[out] out The initialised Lagrange polynomial structure
+ * @param[in]  in  The polynomial of which to compute the Lagrange form
+ * @param[in]  ks  The settings containing the roots of unity to use for DFT
+ * @retval C_CZK_OK      All is well
+ * @retval C_CZK_BADARGS Invalid settings, e.g., fft max_width too low for this polynomial
+ * @retval C_CZK_MALLOC  Memory allocation failed
+ */
 C_KZG_RET new_poly_l_from_poly(poly_l *out, const poly *in, const KZGSettings *ks) {
   TRY(new_poly_l(out, ks->length));
   if (out->length <= in->length) {
@@ -645,6 +667,14 @@ void free_poly(poly *p) {
     }
 }
 
+/**
+ * Reclaim the memory used by a polynomial in Lagrange form.
+ *
+ * @remark To avoid memory leaks, this must be called for polynomials initialised with #new_poly_l or
+ * #new_poly_l_from_poly after use.
+ *
+ * @param[in,out] p The polynomial
+ */
 void free_poly_l(poly_l *p) {
     if (p->values != NULL) {
         free(p->values);