docs(sql): add Doxygen comments to hash and bloom filter index modules (Phase 3 batch 1)

Documented three index module types with comprehensive Doxygen comments:

Modules documented:
- blake3: 6 database objects (type, constructor, extractor, comparator, caster, compare function)
- hmac_256: 6 database objects (type, constructor, extractor, comparator, caster, compare function)
- bloom_filter: 5 database objects (type, constructor, extractor, comparator, caster)

Changes:
- Added @brief descriptions for all types and functions
- Documented @param and @return tags for all parameters and return values
- Clarified "three-way comparison" terminology in compare functions
- Standardized documentation format across all index modules

Progress: 17 database objects documented across 8 files

Author: tobyhede

src/blake3/compare.sql

@@ -3,6 +3,22 @@
 -- REQUIRE: src/blake3/functions.sql
 
 
+--! @brief Compare two encrypted values using Blake3 hash index terms
+--!
+--! Performs a three-way comparison (returns -1/0/1) of encrypted values using
+--! their Blake3 hash index terms. Used internally by the equality operator (=)
+--! for exact-match queries without decryption.
+--!
+--! @param a eql_v2_encrypted First encrypted value to compare
+--! @param b eql_v2_encrypted Second encrypted value to compare
+--! @return Integer -1 if a < b, 0 if a = b, 1 if a > b
+--!
+--! @note NULL values are sorted before non-NULL values
+--! @note Comparison uses underlying text type ordering of Blake3 hashes
+--!
+--! @see eql_v2.blake3
+--! @see eql_v2.has_blake3
+--! @see eql_v2."="
 CREATE FUNCTION eql_v2.compare_blake3(a eql_v2_encrypted, b eql_v2_encrypted)
   RETURNS integer
   IMMUTABLE STRICT PARALLEL SAFE

src/blake3/functions.sql

@@ -1,10 +1,16 @@
 -- REQUIRE: src/schema.sql
 
--- extracts ste_vec index from a jsonb value
-
--- extracts blake3 index from a jsonb value
-
-
+--! @brief Extract Blake3 hash index term from JSONB payload
+--!
+--! Extracts the Blake3 hash value from the 'b3' field of an encrypted
+--! data payload. Used internally for exact-match comparisons.
+--!
+--! @param val JSONB Encrypted data payload containing index terms
+--! @return eql_v2.blake3 Blake3 hash value, or NULL if not present
+--! @throws Exception if 'b3' field is missing when blake3 index is expected
+--!
+--! @see eql_v2.has_blake3
+--! @see eql_v2.compare_blake3
 CREATE FUNCTION eql_v2.blake3(val jsonb)
   RETURNS eql_v2.blake3
   IMMUTABLE STRICT PARALLEL SAFE
@@ -27,8 +33,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
--- extracts blake3 index from an eql_v2_encrypted value
-
+--! @brief Extract Blake3 hash index term from encrypted column value
+--!
+--! Extracts the Blake3 hash from an encrypted column value by accessing
+--! its underlying JSONB data field.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return eql_v2.blake3 Blake3 hash value, or NULL if not present
+--!
+--! @see eql_v2.blake3(jsonb)
 CREATE FUNCTION eql_v2.blake3(val eql_v2_encrypted)
   RETURNS eql_v2.blake3
   IMMUTABLE STRICT PARALLEL SAFE
@@ -39,6 +52,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if JSONB payload contains Blake3 index term
+--!
+--! Tests whether the encrypted data payload includes a 'b3' field,
+--! indicating a Blake3 hash is available for exact-match queries.
+--!
+--! @param val JSONB Encrypted data payload
+--! @return Boolean True if 'b3' field is present and non-null
+--!
+--! @see eql_v2.blake3
 CREATE FUNCTION eql_v2.has_blake3(val jsonb)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -49,6 +71,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if encrypted column value contains Blake3 index term
+--!
+--! 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
+--! @return Boolean True if Blake3 hash is present
+--!
+--! @see eql_v2.has_blake3(jsonb)
 CREATE FUNCTION eql_v2.has_blake3(val eql_v2_encrypted)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE

src/blake3/types.sql

@@ -1,3 +1,11 @@
 -- REQUIRE: src/schema.sql
 
+--! @brief Blake3 hash index term type
+--!
+--! Domain type representing Blake3 cryptographic hash values.
+--! Used for exact-match encrypted searches via the 'unique' index type.
+--! The hash is stored in the 'b3' field of encrypted data payloads.
+--!
+--! @see eql_v2.add_search_config
+--! @note This is a transient type used only during query execution
 CREATE DOMAIN eql_v2.blake3 AS text;

src/bloom_filter/functions.sql

@@ -1,8 +1,17 @@
 -- REQUIRE: src/schema.sql
 
 
--- extracts match index from an emcrypted column
-
+--! @brief Extract Bloom filter index term from JSONB payload
+--!
+--! 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 Encrypted data payload containing index terms
+--! @return eql_v2.bloom_filter Bloom filter as smallint array
+--! @throws Exception if 'bf' field is missing when bloom_filter index is expected
+--!
+--! @see eql_v2.has_bloom_filter
+--! @see eql_v2."~~"
 CREATE FUNCTION eql_v2.bloom_filter(val jsonb)
   RETURNS eql_v2.bloom_filter
   IMMUTABLE STRICT PARALLEL SAFE
@@ -21,8 +30,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
--- extracts unique index from an encrypted column
-
+--! @brief Extract Bloom filter index term from encrypted column value
+--!
+--! Extracts the Bloom filter from an encrypted column value by accessing
+--! its underlying JSONB data field.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return eql_v2.bloom_filter Bloom filter as smallint array
+--!
+--! @see eql_v2.bloom_filter(jsonb)
 CREATE FUNCTION eql_v2.bloom_filter(val eql_v2_encrypted)
   RETURNS eql_v2.bloom_filter
   IMMUTABLE STRICT PARALLEL SAFE
@@ -33,6 +49,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if JSONB payload contains Bloom filter index term
+--!
+--! Tests whether the encrypted data payload includes a 'bf' field,
+--! indicating a Bloom filter is available for pattern-match queries.
+--!
+--! @param val JSONB Encrypted data payload
+--! @return Boolean True if 'bf' field is present and non-null
+--!
+--! @see eql_v2.bloom_filter
 CREATE FUNCTION eql_v2.has_bloom_filter(val jsonb)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -43,6 +68,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if encrypted column value contains Bloom filter index term
+--!
+--! 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
+--! @return Boolean True if Bloom filter is present
+--!
+--! @see eql_v2.has_bloom_filter(jsonb)
 CREATE FUNCTION eql_v2.has_bloom_filter(val eql_v2_encrypted)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE

src/bloom_filter/types.sql

@@ -1,4 +1,13 @@
 -- REQUIRE: src/schema.sql
 
+--! @brief Bloom filter index term type
+--!
+--! Domain type representing Bloom filter bit arrays stored as smallint arrays.
+--! Used for pattern-match encrypted searches via the 'match' index type.
+--! The filter is stored in the 'bf' field of encrypted data payloads.
+--!
+--! @see eql_v2.add_search_config
+--! @see eql_v2."~~"
+--! @note This is a transient type used only during query execution
 CREATE DOMAIN eql_v2.bloom_filter AS smallint[];
 

src/hmac_256/compare.sql

@@ -3,6 +3,22 @@
 -- REQUIRE: src/hmac_256/functions.sql
 
 
+--! @brief Compare two encrypted values using HMAC-SHA256 index terms
+--!
+--! Performs a three-way comparison (returns -1/0/1) of encrypted values using
+--! their HMAC-SHA256 hash index terms. Used internally by the equality operator (=)
+--! for exact-match queries without decryption.
+--!
+--! @param a eql_v2_encrypted First encrypted value to compare
+--! @param b eql_v2_encrypted Second encrypted value to compare
+--! @return Integer -1 if a < b, 0 if a = b, 1 if a > b
+--!
+--! @note NULL values are sorted before non-NULL values
+--! @note Comparison uses underlying text type ordering of HMAC-SHA256 hashes
+--!
+--! @see eql_v2.hmac_256
+--! @see eql_v2.has_hmac_256
+--! @see eql_v2."="
 CREATE FUNCTION eql_v2.compare_hmac_256(a eql_v2_encrypted, b eql_v2_encrypted)
   RETURNS integer
   IMMUTABLE STRICT PARALLEL SAFE

src/hmac_256/functions.sql

@@ -1,8 +1,17 @@
 -- REQUIRE: src/schema.sql
 -- REQUIRE: src/hmac_256/types.sql
 
--- extracts hmac_256 index from an encrypted column
-
+--! @brief Extract HMAC-SHA256 index term from JSONB payload
+--!
+--! Extracts the HMAC-SHA256 hash value from the 'hm' field of an encrypted
+--! data payload. Used internally for exact-match comparisons.
+--!
+--! @param val JSONB Encrypted data payload containing index terms
+--! @return eql_v2.hmac_256 HMAC-SHA256 hash value
+--! @throws Exception if 'hm' field is missing when hmac_256 index is expected
+--!
+--! @see eql_v2.has_hmac_256
+--! @see eql_v2.compare_hmac_256
 CREATE FUNCTION eql_v2.hmac_256(val jsonb)
   RETURNS eql_v2.hmac_256
   IMMUTABLE STRICT PARALLEL SAFE
@@ -20,6 +29,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if JSONB payload contains HMAC-SHA256 index term
+--!
+--! Tests whether the encrypted data payload includes an 'hm' field,
+--! indicating an HMAC-SHA256 hash is available for exact-match queries.
+--!
+--! @param val JSONB Encrypted data payload
+--! @return Boolean True if 'hm' field is present and non-null
+--!
+--! @see eql_v2.hmac_256
 CREATE FUNCTION eql_v2.has_hmac_256(val jsonb)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -30,6 +48,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if encrypted column value contains HMAC-SHA256 index term
+--!
+--! 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
+--! @return Boolean True if HMAC-SHA256 hash is present
+--!
+--! @see eql_v2.has_hmac_256(jsonb)
 CREATE FUNCTION eql_v2.has_hmac_256(val eql_v2_encrypted)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -41,8 +68,15 @@ $$ LANGUAGE plpgsql;
 
 
 
--- extracts hmac_256 index from an encrypted column
-
+--! @brief Extract HMAC-SHA256 index term from encrypted column value
+--!
+--! 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
+--! @return eql_v2.hmac_256 HMAC-SHA256 hash value
+--!
+--! @see eql_v2.hmac_256(jsonb)
 CREATE FUNCTION eql_v2.hmac_256(val eql_v2_encrypted)
   RETURNS eql_v2.hmac_256
   IMMUTABLE STRICT PARALLEL SAFE

src/hmac_256/types.sql

@@ -1,3 +1,11 @@
 -- REQUIRE: src/schema.sql
 
+--! @brief HMAC-SHA256 index term type
+--!
+--! Domain type representing HMAC-SHA256 hash values.
+--! Used for exact-match encrypted searches via the 'unique' index type.
+--! The hash is stored in the 'hm' field of encrypted data payloads.
+--!
+--! @see eql_v2.add_search_config
+--! @note This is a transient type used only during query execution
 CREATE DOMAIN eql_v2.hmac_256 AS text;