docs(sql): fix documentation validation errors

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

- Fix validate-required-tags.sh to handle longer comment blocks
  - Increased tail from 20 to 100 lines to capture complete comments
  - Previous limit was truncating @brief tags in longer documentation blocks
  - Fixes false positive errors for well-documented functions

All validation now passes with 0 errors and 0 warnings.

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-required-tags.sh

@@ -21,7 +21,7 @@ for file in $(find src -name "*.sql" -not -name "*_test.sql"); do
     start=$((line_no - 50))
     [ "$start" -lt 1 ] && start=1
 
-    comment_block=$(sed -n "${start},${line_no}p" "$file" | grep "^--!" | tail -20)
+    comment_block=$(sed -n "${start},${line_no}p" "$file" | grep "^--!" | tail -100)
 
     function_sig=$(sed -n "${line_no}p" "$file")
     # Extract function name (compatible with BSD sed/grep)
@@ -60,7 +60,7 @@ for file in $(find src -name "*.template"); do
     start=$((line_no - 50))
     [ "$start" -lt 1 ] && start=1
 
-    comment_block=$(sed -n "${start},${line_no}p" "$file" | grep "^--!" | tail -20)
+    comment_block=$(sed -n "${start},${line_no}p" "$file" | grep "^--!" | tail -100)
 
     function_sig=$(sed -n "${line_no}p" "$file")
     # Extract function name (compatible with BSD sed/grep)