fix(docs): correct Doxygen parameter documentation format

When Doxygen parses SQL files as C++, it misinterprets function signatures.
For CREATE FUNCTION foo(val type), Doxygen sees 'type' as the parameter name,
not 'val'.

Changed @param documentation from:
  @param val eql_v2_encrypted Description
To:
  @param eql_v2_encrypted Description

This fix applies only to functions with unique parameter types.
Functions with duplicate parameter types (e.g., compare functions with
two eql_v2_encrypted params) still generate warnings and need a
different approach.

Results:
- Fixed 88 @param lines across 20 SQL files
- Reduced parameter warnings from ~64 to 44 (-31%)

Author: tobyhede

src/blake3/functions.sql

@@ -5,7 +5,7 @@
 --! Extracts the Blake3 hash value from the 'b3' field of an encrypted
 --! data payload. Used internally for exact-match comparisons.
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return eql_v2.blake3 Blake3 hash value, or NULL if not present
 --! @throws Exception if 'b3' field is missing when blake3 index is expected
 --!
@@ -38,7 +38,7 @@ $$ LANGUAGE plpgsql;
 --! Extracts the Blake3 hash from an encrypted column value by accessing
 --! its underlying JSONB data field.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return eql_v2.blake3 Blake3 hash value, or NULL if not present
 --!
 --! @see eql_v2.blake3(jsonb)
@@ -57,7 +57,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload includes a 'b3' field,
 --! indicating a Blake3 hash is available for exact-match queries.
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return Boolean True if 'b3' field is present and non-null
 --!
 --! @see eql_v2.blake3
@@ -76,7 +76,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether an encrypted column value includes a Blake3 hash
 --! by checking its underlying JSONB data field.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return Boolean True if Blake3 hash is present
 --!
 --! @see eql_v2.has_blake3(jsonb)

src/bloom_filter/functions.sql

@@ -6,7 +6,7 @@
 --! Extracts the Bloom filter array from the 'bf' field of an encrypted
 --! data payload. Used internally for pattern-match queries (LIKE operator).
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return eql_v2.bloom_filter Bloom filter as smallint array
 --! @throws Exception if 'bf' field is missing when bloom_filter index is expected
 --!
@@ -35,7 +35,7 @@ $$ LANGUAGE plpgsql;
 --! Extracts the Bloom filter from an encrypted column value by accessing
 --! its underlying JSONB data field.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return eql_v2.bloom_filter Bloom filter as smallint array
 --!
 --! @see eql_v2.bloom_filter(jsonb)
@@ -54,7 +54,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload includes a 'bf' field,
 --! indicating a Bloom filter is available for pattern-match queries.
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return Boolean True if 'bf' field is present and non-null
 --!
 --! @see eql_v2.bloom_filter
@@ -73,7 +73,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether an encrypted column value includes a Bloom filter
 --! by checking its underlying JSONB data field.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return Boolean True if Bloom filter is present
 --!
 --! @see eql_v2.has_bloom_filter(jsonb)

src/common.sql

@@ -53,7 +53,7 @@ $$ LANGUAGE plpgsql;
 --! Converts a JSONB array of hex-encoded strings into a PostgreSQL bytea array.
 --! Used for deserializing binary data (like ORE terms) from JSONB storage.
 --!
---! @param val jsonb JSONB array of hex-encoded strings
+--! @param jsonb JSONB array of hex-encoded strings
 --! @return bytea[] Array of decoded binary values
 --!
 --! @note Returns NULL if input is JSON null
@@ -81,7 +81,7 @@ $$ LANGUAGE plpgsql;
 --! Convenience function to emit log messages during testing and debugging.
 --! Uses RAISE NOTICE to output messages to PostgreSQL logs.
 --!
---! @param s text Message to log
+--! @param text Message to log
 --!
 --! @note Primarily used in tests and development
 --! @see eql_v2.log(text, text) for contextual logging

src/config/constraints.sql

@@ -16,7 +16,7 @@
 --! Helper function that extracts all index type names from the configuration's
 --! 'indexes' sections across all tables and columns.
 --!
---! @param val jsonb Configuration data to extract from
+--! @param jsonb Configuration data to extract from
 --! @return SETOF text Index type names (e.g., 'match', 'ore', 'unique', 'ste_vec')
 --!
 --! @note Used by config_check_indexes for validation
@@ -35,7 +35,7 @@ END;
 --! Checks that all index types specified in the configuration are valid.
 --! Valid index types are: match, ore, unique, ste_vec.
 --!
---! @param val jsonb Configuration data to validate
+--! @param jsonb Configuration data to validate
 --! @return boolean True if all index types are valid
 --! @throws Exception if any invalid index type found
 --!
@@ -64,7 +64,7 @@ $$ LANGUAGE plpgsql;
 --! Checks that all 'cast_as' types specified in the configuration are valid.
 --! Valid cast types are: text, int, small_int, big_int, real, double, boolean, date, jsonb.
 --!
---! @param val jsonb Configuration data to validate
+--! @param jsonb Configuration data to validate
 --! @return boolean True if all cast types are valid or no cast types specified
 --! @throws Exception if any invalid cast type found
 --!
@@ -95,7 +95,7 @@ $$ LANGUAGE plpgsql;
 --! Ensures the configuration has a 'tables' field, which is required
 --! to specify which database tables contain encrypted columns.
 --!
---! @param val jsonb Configuration data to validate
+--! @param jsonb Configuration data to validate
 --! @return boolean True if 'tables' field exists
 --! @throws Exception if 'tables' field is missing
 --!
@@ -118,7 +118,7 @@ $$ LANGUAGE plpgsql;
 --! Ensures the configuration has a 'v' (version) field, which tracks
 --! the configuration format version.
 --!
---! @param val jsonb Configuration data to validate
+--! @param jsonb Configuration data to validate
 --! @return boolean True if 'v' field exists
 --! @throws Exception if 'v' field is missing
 --!

src/encrypted/casts.sql

@@ -7,7 +7,7 @@
 --! Wraps a JSONB encrypted payload into the eql_v2_encrypted composite type.
 --! Used internally for type conversions and operator implementations.
 --!
---! @param data jsonb JSONB encrypted payload with structure: {"c": "...", "i": {...}, "k": "...", "v": "2"}
+--! @param jsonb JSONB encrypted payload with structure: {"c": "...", "i": {...}, "k": "...", "v": "2"}
 --! @return eql_v2_encrypted Encrypted value wrapped in composite type
 --!
 --! @note This is primarily used for implicit casts in operator expressions
@@ -41,7 +41,7 @@ CREATE CAST (jsonb AS public.eql_v2_encrypted)
 --! Parses a text representation of encrypted JSONB payload and wraps it
 --! in the eql_v2_encrypted composite type.
 --!
---! @param data text Text representation of JSONB encrypted payload
+--! @param text Text representation of JSONB encrypted payload
 --! @return eql_v2_encrypted Encrypted value wrapped in composite type
 --!
 --! @note Delegates to eql_v2.to_encrypted(jsonb) after parsing text as JSON

src/encrypted/constraints.sql

@@ -9,7 +9,7 @@
 --! Checks that the encrypted JSONB payload contains the required 'i' (ident) field.
 --! The ident field tracks which table and column the encrypted value belongs to.
 --!
---! @param val jsonb Encrypted payload to validate
+--! @param jsonb Encrypted payload to validate
 --! @return Boolean True if 'i' field is present
 --! @throws Exception if 'i' field is missing
 --!
@@ -33,7 +33,7 @@ $$ LANGUAGE plpgsql;
 --! Checks that the 'i' (ident) field contains both 't' (table) and 'c' (column)
 --! subfields, which identify the origin of the encrypted value.
 --!
---! @param val jsonb Encrypted payload to validate
+--! @param jsonb Encrypted payload to validate
 --! @return Boolean True if both 't' and 'c' subfields are present
 --! @throws Exception if 't' or 'c' subfields are missing
 --!
@@ -56,7 +56,7 @@ $$ LANGUAGE plpgsql;
 --! Checks that the encrypted payload has version field 'v' set to '2',
 --! the current EQL v2 payload version.
 --!
---! @param val jsonb Encrypted payload to validate
+--! @param jsonb Encrypted payload to validate
 --! @return Boolean True if 'v' field is present and equals '2'
 --! @throws Exception if 'v' field is missing or not '2'
 --!
@@ -86,7 +86,7 @@ $$ LANGUAGE plpgsql;
 --! Checks that the encrypted payload contains the required 'c' (ciphertext) field
 --! which stores the encrypted data.
 --!
---! @param val jsonb Encrypted payload to validate
+--! @param jsonb Encrypted payload to validate
 --! @return Boolean True if 'c' field is present
 --! @throws Exception if 'c' field is missing
 --!
@@ -113,7 +113,7 @@ $$ LANGUAGE plpgsql;
 --! This function is used in CHECK constraints to ensure encrypted column
 --! data integrity at the database level.
 --!
---! @param val jsonb Encrypted payload to validate
+--! @param jsonb Encrypted payload to validate
 --! @return Boolean True if all structure checks pass
 --! @throws Exception if any required field is missing or invalid
 --!
@@ -144,7 +144,7 @@ END;
 --! Validates an eql_v2_encrypted composite type by checking its underlying
 --! JSONB payload. Delegates to eql_v2.check_encrypted(jsonb).
 --!
---! @param val eql_v2_encrypted Encrypted value to validate
+--! @param eql_v2_encrypted Encrypted value to validate
 --! @return Boolean True if structure is valid
 --! @throws Exception if any required field is missing or invalid
 --!

src/encrypted/functions.sql

@@ -8,7 +8,7 @@
 --! Extracts the ciphertext (c field) from a raw JSONB encrypted value.
 --! The ciphertext is the base64-encoded encrypted data.
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return Text Base64-encoded ciphertext string
 --! @throws Exception if 'c' field is not present in JSONB
 --!
@@ -35,7 +35,7 @@ $$ LANGUAGE plpgsql;
 --! Extracts the ciphertext from an encrypted column value. Convenience
 --! overload that unwraps eql_v2_encrypted type and delegates to JSONB version.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return Text Base64-encoded ciphertext string
 --! @throws Exception if encrypted value is malformed
 --!
@@ -159,7 +159,7 @@ $$ LANGUAGE plpgsql;
 --! Extracts index terms (i) and version (v) from a raw JSONB encrypted value.
 --! Returns metadata object containing searchable index terms without ciphertext.
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return JSONB Metadata object with 'i' (index terms) and 'v' (version) fields
 --!
 --! @example
@@ -187,7 +187,7 @@ $$ LANGUAGE plpgsql;
 --! Convenience overload that unwraps eql_v2_encrypted type and
 --! delegates to JSONB version.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return JSONB Metadata object with 'i' (index terms) and 'v' (version) fields
 --!
 --! @example

src/hmac_256/functions.sql

@@ -6,7 +6,7 @@
 --! Extracts the HMAC-SHA256 hash value from the 'hm' field of an encrypted
 --! data payload. Used internally for exact-match comparisons.
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return eql_v2.hmac_256 HMAC-SHA256 hash value
 --! @throws Exception if 'hm' field is missing when hmac_256 index is expected
 --!
@@ -34,7 +34,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload includes an 'hm' field,
 --! indicating an HMAC-SHA256 hash is available for exact-match queries.
 --!
---! @param val jsonb containing encrypted EQL payload
+--! @param jsonb containing encrypted EQL payload
 --! @return Boolean True if 'hm' field is present and non-null
 --!
 --! @see eql_v2.hmac_256
@@ -53,7 +53,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether an encrypted column value includes an HMAC-SHA256 hash
 --! by checking its underlying JSONB data field.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return Boolean True if HMAC-SHA256 hash is present
 --!
 --! @see eql_v2.has_hmac_256(jsonb)
@@ -73,7 +73,7 @@ $$ LANGUAGE plpgsql;
 --! Extracts the HMAC-SHA256 hash from an encrypted column value by accessing
 --! its underlying JSONB data field.
 --!
---! @param val eql_v2_encrypted Encrypted column value
+--! @param eql_v2_encrypted Encrypted column value
 --! @return eql_v2.hmac_256 HMAC-SHA256 hash value
 --!
 --! @see eql_v2.hmac_256(jsonb)

src/jsonb/functions.sql

@@ -20,8 +20,8 @@
 --! the given selector path. Returns all matching encrypted elements. If multiple
 --! matches form an array, they are wrapped with array metadata.
 --!
---! @param val jsonb Encrypted JSONB payload containing STE vector ('sv')
---! @param selector text Path selector to match against encrypted elements
+--! @param jsonb Encrypted JSONB payload containing STE vector ('sv')
+--! @param text Path selector to match against encrypted elements
 --! @return SETOF eql_v2_encrypted Matching encrypted elements (may return multiple rows)
 --!
 --! @note Returns empty set if selector is not found (does not throw exception)
@@ -109,8 +109,8 @@ $$ LANGUAGE plpgsql;
 --! Overload that accepts encrypted JSONB value and text selector,
 --! extracting the JSONB payload before querying.
 --!
---! @param val eql_v2_encrypted Encrypted JSONB value to query
---! @param selector text Path selector to match against
+--! @param eql_v2_encrypted Encrypted JSONB value to query
+--! @param text Path selector to match against
 --! @return SETOF eql_v2_encrypted Matching encrypted elements
 --!
 --! @example
@@ -137,8 +137,8 @@ $$ LANGUAGE plpgsql;
 --! Tests whether any encrypted elements match the given selector path.
 --! More efficient than jsonb_path_query when only existence check is needed.
 --!
---! @param val jsonb Encrypted JSONB payload to check
---! @param selector text Path selector to test
+--! @param jsonb Encrypted JSONB payload to check
+--! @param text Path selector to test
 --! @return boolean True if matching element exists, false otherwise
 --!
 --! @see eql_v2.jsonb_path_query(jsonb, text)
@@ -180,8 +180,8 @@ $$ LANGUAGE plpgsql;
 --!
 --! Overload that accepts encrypted JSONB value and text selector.
 --!
---! @param val eql_v2_encrypted Encrypted JSONB value to check
---! @param selector text Path selector to test
+--! @param eql_v2_encrypted Encrypted JSONB value to check
+--! @param text Path selector to test
 --! @return boolean True if path exists
 --!
 --! @example
@@ -210,8 +210,8 @@ $$ LANGUAGE plpgsql;
 --! or NULL if no match found. More efficient than jsonb_path_query when
 --! only one result is needed.
 --!
---! @param val jsonb Encrypted JSONB payload to query
---! @param selector text Path selector to match
+--! @param jsonb Encrypted JSONB payload to query
+--! @param text Path selector to match
 --! @return eql_v2_encrypted First matching element or NULL
 --!
 --! @note Uses LIMIT 1 internally for efficiency
@@ -258,8 +258,8 @@ $$ LANGUAGE plpgsql;
 --!
 --! Overload that accepts encrypted JSONB value and text selector.
 --!
---! @param val eql_v2_encrypted Encrypted JSONB value to query
---! @param selector text Path selector to match
+--! @param eql_v2_encrypted Encrypted JSONB value to query
+--! @param text Path selector to match
 --! @return eql_v2_encrypted First matching element or NULL
 --!
 --! @example
@@ -291,7 +291,7 @@ $$ LANGUAGE plpgsql;
 --! elements in the STE vector ('sv'). The encrypted value must have the
 --! array flag ('a') set to true.
 --!
---! @param val jsonb Encrypted JSONB payload representing an array
+--! @param jsonb Encrypted JSONB payload representing an array
 --! @return integer Number of elements in the array
 --! @throws Exception 'cannot get array length of a non-array' if 'a' flag is missing or not true
 --!
@@ -325,7 +325,7 @@ $$ LANGUAGE plpgsql;
 --! Overload that accepts encrypted composite type and extracts the
 --! JSONB payload before computing array length.
 --!
---! @param val eql_v2_encrypted Encrypted array value
+--! @param eql_v2_encrypted Encrypted array value
 --! @return integer Number of elements in the array
 --! @throws Exception if value is not an array
 --!
@@ -354,7 +354,7 @@ $$ LANGUAGE plpgsql;
 --! Each element is returned as an eql_v2_encrypted value with metadata
 --! preserved from the parent array.
 --!
---! @param val jsonb Encrypted JSONB payload representing an array
+--! @param jsonb Encrypted JSONB payload representing an array
 --! @return SETOF eql_v2_encrypted One row per array element
 --! @throws Exception if value is not an array (missing 'a' flag)
 --!
@@ -395,7 +395,7 @@ $$ LANGUAGE plpgsql;
 --! Overload that accepts encrypted composite type and extracts each
 --! array element as a separate row.
 --!
---! @param val eql_v2_encrypted Encrypted array value
+--! @param eql_v2_encrypted Encrypted array value
 --! @return SETOF eql_v2_encrypted One row per array element
 --! @throws Exception if value is not an array
 --!
@@ -422,7 +422,7 @@ $$ LANGUAGE plpgsql;
 --! value (text representation). Unlike jsonb_array_elements, this returns
 --! only the ciphertext 'c' field without metadata.
 --!
---! @param val jsonb Encrypted JSONB payload representing an array
+--! @param jsonb Encrypted JSONB payload representing an array
 --! @return SETOF text One ciphertext string per array element
 --! @throws Exception if value is not an array (missing 'a' flag)
 --!
@@ -456,7 +456,7 @@ $$ LANGUAGE plpgsql;
 --! Overload that accepts encrypted composite type and extracts each
 --! array element's ciphertext as text.
 --!
---! @param val eql_v2_encrypted Encrypted array value
+--! @param eql_v2_encrypted Encrypted array value
 --! @return SETOF text One ciphertext string per array element
 --! @throws Exception if value is not an array
 --!