Add param linter script for C source

.github/workflows/c-tests.yml

@@ -37,6 +37,14 @@ jobs:
           check-path: 'src'
           exclude-regex: 'tinytest.h'
 
+      # Check param formatting.
+      # Only need to check this once.
+      - name: Check param formatting
+        if: matrix.os == 'ubuntu-latest'
+        run: |
+          python3 ../scripts/format_c_params.py
+          git diff --exit-code
+
       # Run tests.
       - name: Test
         run: make test

scripts/convert_trusted_setup.py

@@ -1,12 +1,14 @@
-#!/usr/bin/python3
+#!/usr/bin/env python3
 
 import argparse
 import json
 from typing import TextIO
 
 
 def convert(ts_json: TextIO, ts_text: TextIO) -> None:
-    """Convert trusted setup to text format."""
+    """
+    Convert trusted setup to text format.
+    """
     trusted_setup = json.load(ts_json)
     g1_monomial = trusted_setup["g1_monomial"]
     g1_lagrange = trusted_setup["g1_lagrange"]

scripts/format_c_params.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+
+import glob
+import os
+
+from typing import Sequence
+
+
+def tab(n: int) -> int:
+    """
+    What's the next index of a simulated tab.
+    """
+    a = (n + 3) // 4 * 4
+    return a + 4 if a == n else a
+
+
+def inject_string_at_index(line: str, to_inject: str, index: int) -> str:
+    """
+    Inject a string at a specific index.
+    """
+    return line[:index] + to_inject + line[index:]
+
+
+def delete_chars_at_index(line: str, n: int, index: int) -> str:
+    """
+    Delete characters at a specific index.
+    """
+    return line[:index] + line[index + n:]
+
+
+def find_space_after(line: str, start_index: int) -> int:
+    """
+    Find the first space after some index.
+    """
+    for index, c in enumerate(line[start_index:]):
+        if c == " ":
+            return index + start_index
+
+
+def next_word_index(line: str, start_index: int) -> int:
+    """
+    Find the next word. Assumes start index is not a space.
+    """
+    space_index = line.find(" ", start_index)
+    assert space_index != -1
+
+    # Find the first non-space character after the space
+    non_space_index = space_index + 1
+    while non_space_index < len(line) and line[non_space_index] == " ":
+        non_space_index += 1
+    assert non_space_index < len(line)
+    return non_space_index
+
+
+def format_param_lines(lines: Sequence[str]) -> Sequence[str]:
+    """
+    Given some lines with @param, properly format them.
+    """
+    valid_var_index = 0
+    for line in lines:
+        index = find_space_after(line, line.find("@param"))
+        valid_var_index = max(valid_var_index, tab(index))
+
+    new_lines = []
+    for line in lines:
+        var_index = next_word_index(line, line.find('@param'))
+        if var_index > valid_var_index:
+            spaces_to_delete = var_index - valid_var_index
+            line = delete_chars_at_index(line, spaces_to_delete, var_index - spaces_to_delete)
+        if var_index < valid_var_index:
+            spaces_to_add = valid_var_index - var_index
+            line = inject_string_at_index(line, " " * spaces_to_add, var_index)
+        new_lines.append(line)
+
+    lines = new_lines
+    valid_desc_index = 0
+    for line in lines:
+        index = find_space_after(line, valid_var_index)
+        valid_desc_index = max(valid_desc_index, tab(index))
+
+    new_lines = []
+    for line in lines:
+        desc_index = next_word_index(line, valid_var_index)
+        if desc_index > valid_desc_index:
+            spaces_to_delete = desc_index - valid_desc_index
+            line = delete_chars_at_index(line, spaces_to_delete, desc_index - spaces_to_delete)
+        if desc_index < valid_desc_index:
+            spaces_to_add = valid_desc_index - desc_index
+            line = inject_string_at_index(line, " " * spaces_to_add, desc_index)
+        new_lines.append(line)
+
+    return new_lines
+
+
+def format_params(file_path: str):
+    """
+    Given some file, format all of the @param lines.
+    """
+    with open(file_path, "r") as file:
+        lines = file.readlines()
+
+    param_lines = []
+    modified_lines = []
+    for line in lines:
+        if "@param" in line:
+            param_lines.append(line)
+        else:
+            if len(param_lines) != 0:
+                new_lines = format_param_lines(param_lines)
+                modified_lines.extend(new_lines)
+            modified_lines.append(line)
+            param_lines = []
+
+    with open(file_path, "w") as file:
+        file.writelines(modified_lines)
+
+
+if __name__ == "__main__":
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    src_dir = os.path.join(script_dir, "../src")
+
+    src_files = []
+    src_files += glob.glob(os.path.join(src_dir, "**", "*.c"), recursive=True)
+    src_files += glob.glob(os.path.join(src_dir, "**", "*.h"), recursive=True)
+
+    for f in src_files:
+        format_params(f)

src/Makefile

@@ -251,6 +251,7 @@ analyze: blst $(SOURCE_FILES)
 .PHONY: format
 format:
 	@echo "[+] executing formatter"
+	@python3 ../scripts/format_c_params.py
 	@clang-format -i --sort-includes $(SOURCE_FILES) $(HEADER_FILES)
 
 .PHONY: clean

src/common/bytes.c

@@ -117,8 +117,8 @@ C_KZG_RET bytes_to_kzg_proof(g1_t *out, const Bytes48 *b) {
 /**
  * Map bytes to a BLS field element.
  *
- * @param[out] out The field element to store the result
- * @param[in]  b   A 32-byte array containing the input
+ * @param[out]  out The field element to store the result
+ * @param[in]   b   A 32-byte array containing the input
  */
 void hash_to_bls_field(fr_t *out, const Bytes32 *b) {
     blst_scalar tmp;

src/eip7594/eip7594.c

@@ -300,8 +300,8 @@ static bool commitments_equal(const Bytes48 *a, const Bytes48 *b) {
 /**
  * Helper function to copy one commitment's bytes to another.
  *
- * @param[in]   dst   The destination commitment
- * @param[in]   src   The source commitment
+ * @param[in]   dst The destination commitment
+ * @param[in]   src The source commitment
  */
 static void commitments_copy(Bytes48 *dst, const Bytes48 *src) {
     memcpy(dst->bytes, src->bytes, BYTES_PER_COMMITMENT);
@@ -457,12 +457,12 @@ static C_KZG_RET compute_r_powers_for_verify_cell_kzg_proof_batch(
 /**
  * Compute the sum of the commitments weighted by the powers of r.
  *
- * @param[out] sum_of_commitments_out   The resulting G1 sum of the commitments
- * @param[in]  unique_commitments       Array of unique commitments
- * @param[in]  commitment_indices       Indices mapping to unique commitments
- * @param[in]  r_powers                 Array of powers of r used for weighting
- * @param[in]  num_commitments          The number of unique commitments
- * @param[in]  num_cells                The number of cells
+ * @param[out]  sum_of_commitments_out  The resulting G1 sum of the commitments
+ * @param[in]   unique_commitments      Array of unique commitments
+ * @param[in]   commitment_indices      Indices mapping to unique commitments
+ * @param[in]   r_powers                Array of powers of r used for weighting
+ * @param[in]   num_commitments         The number of unique commitments
+ * @param[in]   num_cells               The number of cells
  */
 static C_KZG_RET compute_weighted_sum_of_commitments(
     g1_t *sum_of_commitments_out,
@@ -686,12 +686,12 @@ static C_KZG_RET compute_commitment_to_aggregated_interpolation_poly(
 /**
  * Compute weighted sum of proofs.
  *
- * @param[out] weighted_proof_lincomb The resulting G1 sum of the proofs scaled by coset factors
- * @param[in]  proofs_g1              Array of G1 elements representing the proofs
- * @param[in]  r_powers               Array of powers of r used for weighting
- * @param[in]  cell_indices           Array of cell indices
- * @param[in]  num_cells              The number of cells
- * @param[in]  s                      The trusted setup containing roots of unity
+ * @param[out]  weighted_proof_lincomb  The resulting G1 sum of the proofs scaled by coset factors
+ * @param[in]   proofs_g1               Array of G1 elements representing the proofs
+ * @param[in]   r_powers                Array of powers of r used for weighting
+ * @param[in]   cell_indices            Array of cell indices
+ * @param[in]   num_cells               The number of cells
+ * @param[in]   s                       The trusted setup containing roots of unity
  */
 static C_KZG_RET computed_weighted_sum_of_proofs(
     g1_t *weighted_proof_sum_out,
@@ -734,8 +734,6 @@ static C_KZG_RET computed_weighted_sum_of_proofs(
  * @param[in]   proofs_bytes        The proofs for the cells
  * @param[in]   num_cells           The number of cells provided
  * @param[in]   s                   The trusted setup
- *
- * @remark cells[i] is associated with commitments_bytes[commitment_indices[i]].
  */
 C_KZG_RET verify_cell_kzg_proof_batch(
     bool *ok,

src/eip7594/recovery.c

@@ -35,10 +35,10 @@
  * Uses straightforward long multiplication to calculate the product of `(x - r_i)` where `r_i` is
  * the i'th root. This results in a poly of degree roots_len.
  *
- * @param[in,out]   poly         The zero polynomial for roots
- * @param[in,out]   poly_len     The length of poly
- * @param[in]       roots        The array of roots
- * @param[in]       roots_len    The number of roots
+ * @param[in,out]   poly        The zero polynomial for roots
+ * @param[in,out]   poly_len    The length of poly
+ * @param[in]       roots       The array of roots
+ * @param[in]       roots_len   The number of roots
  *
  * @remark These do not have to be roots of unity. They are roots of a polynomial.
  * @remark The `poly` array must be at least `roots_len + 1` in length.
@@ -191,11 +191,11 @@ static bool is_in_array(const uint64_t *arr, size_t arr_size, uint64_t value) {
  * original. Assumes that the inverse FFT of the original data has the upper half of its values
  * equal to zero.
  *
- * @param[out]  reconstructed_data_out   Array of size FIELD_ELEMENTS_PER_EXT_BLOB to recover cells
- * @param[in]   cell_indices             An array with the available cell indices we have
- * @param[in]   num_cells                The size of the `cell_indices` array
- * @param[in]   cells                    An array of size FIELD_ELEMENTS_PER_EXT_BLOB with the cells
- * @param[in]   s                        The trusted setup
+ * @param[out]  reconstructed_data_out  Array of size FIELD_ELEMENTS_PER_EXT_BLOB to recover cells
+ * @param[in]   cell_indices            An array with the available cell indices we have
+ * @param[in]   num_cells               The size of the `cell_indices` array
+ * @param[in]   cells                   An array of size FIELD_ELEMENTS_PER_EXT_BLOB with the cells
+ * @param[in]   s                       The trusted setup
  *
  * @remark `reconstructed_data_out` and `cells` can point to the same memory.
  * @remark The array `cells` must be in the correct order (according to cell_indices).