docs(sql): fix documentation validation errors

Add missing documentation tags to operators:
- src/operators/<>.sql: Add @param and @return for JSONB overload
- src/operators/~~.sql: Add @brief, @param, @return for operator

Add validation script:
- tasks/validate-documented-sql.sh: SQL syntax validation (optional)

These fixes ensure all documented functions have required @brief, @param,
and @return tags for proper Doxygen output.

Source: phase-4-doxygen commit b4d6b4d, 01ab2f8

Author: tobyhede

src/operators/<>.sql

@@ -83,6 +83,11 @@ CREATE OPERATOR <> (
 );
 
 --! @brief <> operator for JSONB and encrypted value
+--!
+--! @param a jsonb Plain JSONB value
+--! @param b eql_v2_encrypted Encrypted value
+--! @return boolean True if values are not equal
+--!
 --! @see eql_v2."<>"(eql_v2_encrypted, eql_v2_encrypted)
 CREATE FUNCTION eql_v2."<>"(a jsonb, b eql_v2_encrypted)
   RETURNS boolean

src/operators/~~.sql

@@ -63,6 +63,12 @@ $$ LANGUAGE SQL;
 --! SELECT * FROM customers
 --! WHERE encrypted_name ~~ 'John%'::text::eql_v2_encrypted;
 --!
+--! @brief SQL LIKE operator (~~ operator) for encrypted text pattern matching
+--!
+--! @param a eql_v2_encrypted Left operand (encrypted value)
+--! @param b eql_v2_encrypted Right operand (encrypted pattern)
+--! @return boolean True if pattern matches
+--!
 --! @note Requires match index: eql_v2.add_search_config(table, column, 'match')
 --! @see eql_v2.like
 --! @see eql_v2.add_search_config

tasks/validate-documented-sql.sh

@@ -0,0 +1,55 @@
+#!/bin/bash
+# tasks/validate-documented-sql.sh
+# Validates SQL syntax for all documented files
+
+set -e
+
+cd "$(dirname "$0")/.."
+
+PGHOST=${PGHOST:-localhost}
+PGPORT=${PGPORT:-7432}
+PGUSER=${PGUSER:-cipherstash}
+PGPASSWORD=${PGPASSWORD:-password}
+PGDATABASE=${PGDATABASE:-postgres}
+
+echo "Validating SQL syntax for all documented files..."
+echo ""
+
+errors=0
+validated=0
+
+for file in $(find src -name "*.sql" -not -name "*_test.sql" | sort); do
+  echo -n "Validating $file... "
+
+  # Capture both stdout and stderr
+  error_output=$(PGPASSWORD="$PGPASSWORD" psql -h "$PGHOST" -p "$PGPORT" -U "$PGUSER" -d "$PGDATABASE" \
+          -f "$file" --set ON_ERROR_STOP=1 -q 2>&1) || exit_code=$?
+
+  if [ "${exit_code:-0}" -eq 0 ]; then
+    echo "✓"
+    validated=$((validated + 1))
+  else
+    echo "✗ SYNTAX ERROR"
+    echo "  Error in: $file"
+    echo "  Details:"
+    echo "$error_output" | tail -10 | sed 's/^/    /'
+    echo ""
+    errors=$((errors + 1))
+  fi
+  exit_code=0
+done
+
+echo ""
+echo "Validation complete:"
+echo "  Validated: $validated"
+echo "  Errors: $errors"
+
+if [ $errors -gt 0 ]; then
+  echo ""
+  echo "❌ Validation failed with $errors errors"
+  exit 1
+else
+  echo ""
+  echo "✅ All SQL files validated successfully"
+  exit 0
+fi