Merge pull request #496 from jtraglia/consistent-param-docs

Reformat some function param docs for consistency

src/common/alloc.c

@@ -29,10 +29,10 @@
 /**
  * Wrapped malloc() that reports failures to allocate.
  *
- * @remark Will return C_KZG_BADARGS if the requested size is zero.
+ * @param[out]  out     Pointer to the allocated space
+ * @param[in]   size    The number of bytes to be allocated
  *
- * @param[out] out  Pointer to the allocated space
- * @param[in]  size The number of bytes to be allocated
+ * @remark Will return C_KZG_BADARGS if the requested size is zero.
  */
 C_KZG_RET c_kzg_malloc(void **out, size_t size) {
     *out = NULL;
@@ -44,9 +44,9 @@ C_KZG_RET c_kzg_malloc(void **out, size_t size) {
 /**
  * Wrapped calloc() that reports failures to allocate.
  *
- * @param[out] out   Pointer to the allocated space
- * @param[in]  count The number of elements
- * @param[in]  size  The size of each element
+ * @param[out]  out     Pointer to the allocated space
+ * @param[in]   count   The number of elements
+ * @param[in]   size    The size of each element
  *
  * @remark Will return C_KZG_BADARGS if the requested size is zero.
  */
@@ -60,8 +60,8 @@ C_KZG_RET c_kzg_calloc(void **out, size_t count, size_t size) {
 /**
  * Allocate memory for an array of G1 group elements.
  *
- * @param[out] x Pointer to the allocated space
- * @param[in]  n The number of G1 elements to be allocated
+ * @param[out]  x   Pointer to the allocated space
+ * @param[in]   n   The number of G1 elements to be allocated
  *
  * @remark Free the space later using c_kzg_free().
  */
@@ -72,8 +72,8 @@ C_KZG_RET new_g1_array(g1_t **x, size_t n) {
 /**
  * Allocate memory for an array of G2 group elements.
  *
- * @param[out] x Pointer to the allocated space
- * @param[in]  n The number of G2 elements to be allocated
+ * @param[out]  x   Pointer to the allocated space
+ * @param[in]   n   The number of G2 elements to be allocated
  *
  * @remark Free the space later using c_kzg_free().
  */
@@ -84,8 +84,8 @@ C_KZG_RET new_g2_array(g2_t **x, size_t n) {
 /**
  * Allocate memory for an array of field elements.
  *
- * @param[out] x Pointer to the allocated space
- * @param[in]  n The number of field elements to be allocated
+ * @param[out]  x   Pointer to the allocated space
+ * @param[in]   n   The number of field elements to be allocated
  *
  * @remark Free the space later using c_kzg_free().
  */
@@ -96,8 +96,8 @@ C_KZG_RET new_fr_array(fr_t **x, size_t n) {
 /**
  * Allocate memory for an array of booleans.
  *
- * @param[out] x Pointer to the allocated space
- * @param[in]  n The number of booleans to be allocated
+ * @param[out]  x   Pointer to the allocated space
+ * @param[in]   n   The number of booleans to be allocated
  *
  * @remark Free the space later using c_kzg_free().
  */

src/common/bytes.c

@@ -21,8 +21,8 @@
 /**
  * Serialize a 64-bit unsigned integer into bytes.
  *
- * @param[out] out An 8-byte array to store the serialized integer
- * @param[in]  n   The integer to be serialized
+ * @param[out]  out An 8-byte array to store the serialized integer
+ * @param[in]   n   The integer to be serialized
  *
  * @remark The output format is big-endian.
  */
@@ -36,8 +36,8 @@ void bytes_from_uint64(uint8_t out[8], uint64_t n) {
 /**
  * Serialize a G1 group element into bytes.
  *
- * @param[out] out A 48-byte array to store the serialized G1 element
- * @param[in]  in  The G1 element to be serialized
+ * @param[out]  out A 48-byte array to store the serialized G1 element
+ * @param[in]   in  The G1 element to be serialized
  */
 void bytes_from_g1(Bytes48 *out, const g1_t *in) {
     blst_p1_compress(out->bytes, in);
@@ -46,8 +46,8 @@ void bytes_from_g1(Bytes48 *out, const g1_t *in) {
 /**
  * Serialize a BLS field element into bytes.
  *
- * @param[out] out A 32-byte array to store the serialized field element
- * @param[in] in The field element to be serialized
+ * @param[out]  out A 32-byte array to store the serialized field element
+ * @param[in]   in  The field element to be serialized
  */
 void bytes_from_bls_field(Bytes32 *out, const fr_t *in) {
     blst_scalar s;
@@ -58,8 +58,8 @@ void bytes_from_bls_field(Bytes32 *out, const fr_t *in) {
 /**
  * Convert untrusted bytes to a trusted and validated BLS scalar field element.
  *
- * @param[out] out The field element to store the deserialized data
- * @param[in]  b   A 32-byte array containing the serialized field element
+ * @param[out]  out The field element to store the deserialized data
+ * @param[in]   b   A 32-byte array containing the serialized field element
  */
 C_KZG_RET bytes_to_bls_field(fr_t *out, const Bytes32 *b) {
     blst_scalar tmp;

src/common/ec.c

@@ -22,9 +22,9 @@
 /**
  * Subtraction of G1 group elements.
  *
- * @param[out] out `a - b`
- * @param[in]  a   A G1 group element
- * @param[in]  b   The G1 group element to be subtracted
+ * @param[out]  out The result, `a - b`
+ * @param[in]   a   A G1 group element
+ * @param[in]   b   The G1 group element to be subtracted
  */
 void g1_sub(g1_t *out, const g1_t *a, const g1_t *b) {
     g1_t bneg = *b;
@@ -35,9 +35,9 @@ void g1_sub(g1_t *out, const g1_t *a, const g1_t *b) {
 /**
  * Multiply a G1 group element by a field element.
  *
- * @param[out] out  `a * b`
- * @param[in]  a    The G1 group element
- * @param[in]  b    The multiplier
+ * @param[out]  out The result, `a * b`
+ * @param[in]   a   The G1 group element
+ * @param[in]   b   The multiplier
  */
 void g1_mul(g1_t *out, const g1_t *a, const fr_t *b) {
     blst_scalar s;

src/common/fr.c

@@ -26,8 +26,8 @@
  * @param[in]   a   The first element
  * @param[in]   b   The second element
  *
- * @retval true     The two elements are equal.
- * @retval false    The two elements are not equal.
+ * @retval  true    The two elements are equal.
+ * @retval  false   The two elements are not equal.
  */
 bool fr_equal(const fr_t *a, const fr_t *b) {
     uint64_t _a[4], _b[4];
@@ -39,10 +39,10 @@ bool fr_equal(const fr_t *a, const fr_t *b) {
 /**
  * Test whether the operand is one in the finite field.
  *
- * @param[in] p The field element to be checked
+ * @param[in]   p   The field element to be checked
  *
- * @retval true  The element is one
- * @retval false The element is not one
+ * @retval  true    The element is one
+ * @retval  false   The element is not one
  */
 bool fr_is_one(const fr_t *p) {
     uint64_t a[4];
@@ -53,10 +53,10 @@ bool fr_is_one(const fr_t *p) {
 /**
  * Test whether the operand is null (all 0xff's).
  *
- * @param[in] p The field element to be checked
+ * @param[in]   p   The field element to be checked
  *
- * @retval true  The element is null
- * @retval false The element is not null
+ * @retval  true    The element is null
+ * @retval  false   The element is not null
  */
 bool fr_is_null(const fr_t *p) {
     return fr_equal(p, &FR_NULL);
@@ -65,9 +65,9 @@ bool fr_is_null(const fr_t *p) {
 /**
  * Divide a field element by another.
  *
- * @param[out] out `a` divided by `b` in the field
- * @param[in]  a   The dividend
- * @param[in]  b   The divisor
+ * @param[out]  out The result, `a / b`
+ * @param[in]   a   The dividend
+ * @param[in]   b   The divisor
  *
  * @remark The behavior for `b == 0` is unspecified.
  * @remark This function supports in-place computation.
@@ -83,9 +83,9 @@ void fr_div(fr_t *out, const fr_t *a, const fr_t *b) {
  *
  * Uses square and multiply for log(n) performance.
  *
- * @param[out] out `a` raised to the power of `n`
- * @param[in]  a   The field element to be exponentiated
- * @param[in]  n   The exponent
+ * @param[out]  out The result, `a**n`
+ * @param[in]   a   The field element to be exponentiated
+ * @param[in]   n   The exponent
  *
  * @remark A 64-bit exponent is sufficient for our needs here.
  * @remark This function does support in-place computation.
@@ -106,8 +106,8 @@ void fr_pow(fr_t *out, const fr_t *a, uint64_t n) {
 /**
  * Create a field element from a single 64-bit unsigned integer.
  *
- * @param[out] out The field element equivalent of `n`
- * @param[in]  n   The 64-bit integer to be converted
+ * @param[out]  out The field element equivalent of `n`
+ * @param[in]   n   The 64-bit integer to be converted
  *
  * @remark This can only generate a tiny fraction of possible field elements,
  *         and is mostly useful for testing.

src/common/lincomb.c

@@ -24,7 +24,12 @@
  *
  * Calculates `[coeffs_0]p_0 + [coeffs_1]p_1 + ... + [coeffs_n]p_n` where `n` is `len - 1`.
  *
- * This function computes the result naively without using Pippenger's algorithm.
+ * @param[out]  out     The resulting sum-product
+ * @param[in]   p       Array of G1 group elements, length `len`
+ * @param[in]   coeffs  Array of field elements, length `len`
+ * @param[in]   len     The number of group/field elements
+ *
+ * @remark This function computes the result naively without using Pippenger's algorithm.
  */
 void g1_lincomb_naive(g1_t *out, const g1_t *p, const fr_t *coeffs, size_t len) {
     g1_t tmp;
@@ -40,10 +45,10 @@ void g1_lincomb_naive(g1_t *out, const g1_t *p, const fr_t *coeffs, size_t len)
  *
  * Calculates `[coeffs_0]p_0 + [coeffs_1]p_1 + ... + [coeffs_n]p_n` where `n` is `len - 1`.
  *
- * @param[out] out    The resulting sum-product
- * @param[in]  p      Array of G1 group elements, length `len`
- * @param[in]  coeffs Array of field elements, length `len`
- * @param[in]  len    The number of group/field elements
+ * @param[out]  out     The resulting sum-product
+ * @param[in]   p       Array of G1 group elements, length `len`
+ * @param[in]   coeffs  Array of field elements, length `len`
+ * @param[in]   len     The number of group/field elements
  *
  * @remark This function CAN be called with the point at infinity in `p`.
  * @remark While this function is significantly faster than g1_lincomb_naive(), we refrain from

src/common/utils.c

@@ -24,7 +24,7 @@
 /**
  * Utility function to test whether the argument is a power of two.
  *
- * @param[in] n The number to test
+ * @param[in]   n   The number to test
  *
  * @return True if `n` is zero or a power of two, otherwise false.
  *
@@ -39,7 +39,7 @@ bool is_power_of_two(uint64_t n) {
 /**
  * Calculate log base two of a power of two.
  *
- * @param[in] n The power of two
+ * @param[in]   n   The power of two
  *
  * @return The log base two of n.
  *
@@ -89,9 +89,9 @@ uint64_t reverse_bits_limited(uint64_t n, uint64_t value) {
 /**
  * Reorder an array in reverse bit order of its indices.
  *
- * @param[in,out] values The array, which is re-ordered in-place
- * @param[in]     size   The size in bytes of an element of the array
- * @param[in]     n      The length of the array, must be a power of two strictly greater than 1
+ * @param[in,out]   values  The array, which is re-ordered in-place
+ * @param[in]       size    The size in bytes of an element of the array
+ * @param[in]       n       The length of the array, must be a power of two strictly greater than 1
  *
  * @remark Operates in-place on the array.
  * @remark Can handle arrays of any type: provide the element size in `size`.
@@ -153,10 +153,10 @@ void compute_powers(fr_t *out, const fr_t *x, size_t n) {
  *
  * Tests whether `e(a1, a2) == e(b1, b2)`.
  *
- * @param[in] a1 A G1 group point for the first pairing
- * @param[in] a2 A G2 group point for the first pairing
- * @param[in] b1 A G1 group point for the second pairing
- * @param[in] b2 A G2 group point for the second pairing
+ * @param[in]   a1  A G1 group point for the first pairing
+ * @param[in]   a2  A G2 group point for the first pairing
+ * @param[in]   b1  A G1 group point for the second pairing
+ * @param[in]   b2  A G2 group point for the second pairing
  *
  * @retval true  The pairings were equal
  * @retval false The pairings were not equal