docs(operators): complete Phase 2 - document JSONB and support functions

Add comprehensive Doxygen documentation to remaining operator files:

JSONB field accessor operators:
- -> (field accessor, 3 overloads: text, encrypted, integer)
- ->> (text-returning accessor, 2 overloads)
- @> (contains operator for ste_vec)
- <@ (contained-by operator, reverse of @>)

Comparison support functions:
- compare.sql: Core comparison with ORE priority cascade
- order_by.sql: ORE term extraction for ORDER BY clauses
- operator_class.sql: Btree operator family/class definitions

All files now include:
- @brief descriptions explaining operator purpose
- @param/@return type documentation
- @example usage demonstrations
- @note for important implementation details
- @see cross-references to related functions

Phase 2 (Core Modules - Operators) now complete.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: tobyhede

src/operators/->.sql

@@ -1,25 +1,34 @@
-
 -- REQUIRE: src/schema.sql
 -- REQUIRE: src/encrypted/types.sql
 -- REQUIRE: src/encrypted/functions.sql
 
-
---
--- The -> operator returns an encrypted matching the provided selector
---
--- Encyprted JSON is represented as an array of `eql_v2_encrypted`.
--- Each `eql_v2_encrypted` value has a selector, ciphertext, and an index term
---
---     {
---       "sv": [ {"c": "", "s": "", "b3": "" } ]
---     }
---
--- Note on oeprator resolution:
---   Assignment casts are considered for operator resolution (see PostgreSQL docs),
---   the system may pick the "more specific" one, which is the one with both arguments of the same type.
---
--- This means that to use the text operator, the parameter will need to be cast to text
---
+--! @brief JSONB field accessor operator for encrypted values (->)
+--!
+--! Implements the -> operator to access fields/elements from encrypted JSONB data.
+--! Returns encrypted value matching the provided selector without decryption.
+--!
+--! Encrypted JSON is represented as an array of eql_v2_encrypted values in the ste_vec format.
+--! Each element has a selector, ciphertext, and index terms:
+--!     {"sv": [{"c": "", "s": "", "b3": ""}]}
+--!
+--! Provides three overloads:
+--! - (eql_v2_encrypted, text) - Field name selector
+--! - (eql_v2_encrypted, eql_v2_encrypted) - Encrypted selector
+--! - (eql_v2_encrypted, integer) - Array index selector (0-based)
+--!
+--! @note Operator resolution: Assignment casts are considered (PostgreSQL standard behavior).
+--! To use text selector, parameter may need explicit cast to text.
+--!
+--! @see eql_v2.ste_vec
+--! @see eql_v2.selector
+--! @see eql_v2."->>"
+
+--! @brief -> operator with text selector
+--! @param e eql_v2_encrypted Encrypted JSONB data
+--! @param selector text Field name to extract
+--! @return eql_v2_encrypted Encrypted value at selector
+--! @example
+--! SELECT encrypted_json -> 'field_name' FROM table;
 CREATE FUNCTION eql_v2."->"(e eql_v2_encrypted, selector text)
   RETURNS eql_v2_encrypted
   IMMUTABLE STRICT PARALLEL SAFE
@@ -58,7 +67,11 @@ CREATE OPERATOR ->(
 
 ---------------------------------------------------
 
-
+--! @brief -> operator with encrypted selector
+--! @param e eql_v2_encrypted Encrypted JSONB data
+--! @param selector eql_v2_encrypted Encrypted field selector
+--! @return eql_v2_encrypted Encrypted value at selector
+--! @see eql_v2."->"(eql_v2_encrypted, text)
 CREATE FUNCTION eql_v2."->"(e eql_v2_encrypted, selector eql_v2_encrypted)
   RETURNS eql_v2_encrypted
   IMMUTABLE STRICT PARALLEL SAFE
@@ -79,7 +92,14 @@ CREATE OPERATOR ->(
 
 ---------------------------------------------------
 
-
+--! @brief -> operator with integer array index
+--! @param e eql_v2_encrypted Encrypted array data
+--! @param selector integer Array index (0-based, JSONB convention)
+--! @return eql_v2_encrypted Encrypted value at array index
+--! @note Array index is 0-based (JSONB standard) despite PostgreSQL arrays being 1-based
+--! @example
+--! SELECT encrypted_array -> 0 FROM table;
+--! @see eql_v2.is_ste_vec_array
 CREATE FUNCTION eql_v2."->"(e eql_v2_encrypted, selector integer)
   RETURNS eql_v2_encrypted
   IMMUTABLE STRICT PARALLEL SAFE

src/operators/->>.sql

@@ -2,8 +2,24 @@
 -- REQUIRE: src/encrypted/types.sql
 -- REQUIRE: src/encrypted/functions.sql
 
+--! @brief JSONB field accessor operator returning text (->>)
+--!
+--! Implements the ->> operator to access fields/elements from encrypted JSONB data,
+--! returning the result as text (still encrypted). Text-returning version of -> operator.
+--!
+--! Provides two overloads:
+--! - (eql_v2_encrypted, text) - Field name selector
+--! - (eql_v2_encrypted, eql_v2_encrypted) - Encrypted selector
+--!
+--! @see eql_v2."->"
+--! @see eql_v2.selector
 
-
+--! @brief ->> operator with text selector
+--! @param e eql_v2_encrypted Encrypted JSONB data
+--! @param selector text Field name to extract
+--! @return text Encrypted value at selector as text
+--! @example
+--! SELECT encrypted_json ->> 'field_name' FROM table;
 CREATE FUNCTION eql_v2."->>"(e eql_v2_encrypted, selector text)
   RETURNS text
 IMMUTABLE STRICT PARALLEL SAFE
@@ -28,7 +44,11 @@ CREATE OPERATOR ->> (
 
 ---------------------------------------------------
 
-
+--! @brief ->> operator with encrypted selector
+--! @param e eql_v2_encrypted Encrypted JSONB data
+--! @param selector eql_v2_encrypted Encrypted field selector
+--! @return text Encrypted value at selector as text
+--! @see eql_v2."->>"(eql_v2_encrypted, text)
 CREATE FUNCTION eql_v2."->>"(e eql_v2_encrypted, selector eql_v2_encrypted)
   RETURNS text
   IMMUTABLE STRICT PARALLEL SAFE

src/operators/<@.sql

@@ -2,7 +2,27 @@
 -- REQUIRE: src/encrypted/types.sql
 -- REQUIRE: src/ste_vec/functions.sql
 
-
+--! @brief Contained-by operator for encrypted values (<@)
+--!
+--! Implements the <@ (contained-by) operator for testing if left encrypted value
+--! is contained by the right encrypted value. Uses ste_vec (secure tree encoding vector)
+--! index terms for containment testing without decryption. Reverse of @> operator.
+--!
+--! Primarily used for encrypted array or set containment queries.
+--!
+--! @param a eql_v2_encrypted Left operand (contained value)
+--! @param b eql_v2_encrypted Right operand (container)
+--! @return Boolean True if a is contained by b
+--!
+--! @example
+--! -- Check if value is contained in encrypted array
+--! SELECT * FROM documents
+--! WHERE '["security"]'::jsonb::eql_v2_encrypted <@ encrypted_tags;
+--!
+--! @note Requires ste_vec index configuration
+--! @see eql_v2.ste_vec_contains
+--! @see eql_v2.\"@>\"
+--! @see eql_v2.add_search_config
 
 CREATE FUNCTION eql_v2."<@"(a eql_v2_encrypted, b eql_v2_encrypted)
 RETURNS boolean AS $$

src/operators/@>.sql

@@ -2,8 +2,26 @@
 -- REQUIRE: src/encrypted/types.sql
 -- REQUIRE: src/ste_vec/functions.sql
 
-
-
+--! @brief Contains operator for encrypted values (@>)
+--!
+--! Implements the @> (contains) operator for testing if left encrypted value
+--! contains the right encrypted value. Uses ste_vec (secure tree encoding vector)
+--! index terms for containment testing without decryption.
+--!
+--! Primarily used for encrypted array or set containment queries.
+--!
+--! @param a eql_v2_encrypted Left operand (container)
+--! @param b eql_v2_encrypted Right operand (contained value)
+--! @return Boolean True if a contains b
+--!
+--! @example
+--! -- Check if encrypted array contains value
+--! SELECT * FROM documents
+--! WHERE encrypted_tags @> '["security"]'::jsonb::eql_v2_encrypted;
+--!
+--! @note Requires ste_vec index configuration
+--! @see eql_v2.ste_vec_contains
+--! @see eql_v2.add_search_config
 CREATE FUNCTION eql_v2."@>"(a eql_v2_encrypted, b eql_v2_encrypted)
 RETURNS boolean AS $$
   SELECT eql_v2.ste_vec_contains(a, b)

src/operators/compare.sql

@@ -17,30 +17,31 @@
 -- REQUIRE: src/ore_cllw_var_8/types.sql
 -- REQUIRE: src/ore_cllw_var_8/functions.sql
 
-
---
--- Compare two eql_v2_encrypted values
---
--- Function is used to implement all operators required for btree indexing"
---      - `<`
---      - `<=`
---      - `=`
---      - `>=`
---      - `>`
---
---
--- Index terms are checked in the following order:
---    - `ore_block_u64_8_256`
---    - `ore_cllw_u64_8`
---    - `ore_cllw_var_8`
---    - `hmac_256`
---    - `blake3`
---
--- The first index term present for both values is used for comparsion.
---
--- If no index terms are found, the encrypted data is compared as a jsonb literal.
--- Btree index must have a consistent ordering for a given state, without this text fallback, database errors with "lock BufferContent is not held"
---
+--! @brief Core comparison function for encrypted values
+--!
+--! Compares two encrypted values using their index terms without decryption.
+--! This function implements all comparison operators required for btree indexing
+--! (<, <=, =, >=, >).
+--!
+--! Index terms are checked in the following priority order:
+--! 1. ore_block_u64_8_256 (Order-Revealing Encryption)
+--! 2. ore_cllw_u64_8 (Order-Revealing Encryption)
+--! 3. ore_cllw_var_8 (Order-Revealing Encryption)
+--! 4. hmac_256 (Hash-based equality)
+--! 5. blake3 (Hash-based equality)
+--!
+--! The first index term type present in both values is used for comparison.
+--! If no matching index terms are found, falls back to JSONB literal comparison
+--! to ensure consistent ordering (required for btree correctness).
+--!
+--! @param a eql_v2_encrypted First encrypted value
+--! @param b eql_v2_encrypted Second encrypted value
+--! @return integer -1 if a < b, 0 if a = b, 1 if a > b
+--!
+--! @note Literal fallback prevents "lock BufferContent is not held" errors
+--! @see eql_v2.compare_ore_block_u64_8_256
+--! @see eql_v2.compare_blake3
+--! @see eql_v2.compare_hmac_256
 CREATE FUNCTION eql_v2.compare(a eql_v2_encrypted, b eql_v2_encrypted)
   RETURNS integer
   IMMUTABLE STRICT PARALLEL SAFE

src/operators/operator_class.sql

@@ -8,6 +8,21 @@
 -- REQUIRE: src/operators/>=.sql
 -- REQUIRE: src/operators/>.sql
 
+--! @brief PostgreSQL operator class definitions for encrypted value indexing
+--!
+--! Defines the operator family and operator class required for btree indexing
+--! of encrypted values. This enables PostgreSQL to use encrypted columns in:
+--! - CREATE INDEX statements
+--! - ORDER BY clauses
+--! - Range queries
+--! - Primary key constraints
+--!
+--! The operator class maps the five comparison operators (<, <=, =, >=, >)
+--! to the eql_v2.compare() support function for btree index operations.
+--!
+--! @note This is the default operator class for eql_v2_encrypted type
+--! @see eql_v2.compare
+--! @see PostgreSQL documentation on operator classes
 
 --------------------
 

src/operators/order_by.sql

@@ -4,9 +4,21 @@
 -- REQUIRE: src/ore_cllw_u64_8/types.sql
 -- REQUIRE: src/ore_cllw_u64_8/functions.sql
 
--- order_by function for ordering when operators are not available.
---
---
+--! @brief Extract ORE index term for ordering encrypted values
+--!
+--! Helper function that extracts the ore_block_u64_8_256 index term from an encrypted value
+--! for use in ORDER BY clauses when comparison operators are not appropriate or available.
+--!
+--! @param a eql_v2_encrypted Encrypted value to extract order term from
+--! @return eql_v2.ore_block_u64_8_256 ORE index term for ordering
+--!
+--! @example
+--! -- Order encrypted values without using comparison operators
+--! SELECT * FROM users ORDER BY eql_v2.order_by(encrypted_age);
+--!
+--! @note Requires 'ore' index configuration on the column
+--! @see eql_v2.ore_block_u64_8_256
+--! @see eql_v2.add_search_config
 CREATE FUNCTION eql_v2.order_by(a eql_v2_encrypted)
   RETURNS eql_v2.ore_block_u64_8_256
   IMMUTABLE STRICT PARALLEL SAFE