docs(sql): document config module and core types (Phase 2 checkpoint)

Add Doxygen-style documentation to core customer-facing modules:

Config module (public):
- add_search_config: Configure searchable encryption indexes
- remove_search_config: Remove index configurations
- modify_search_config: Update index configurations
- migrate_config: Transition pending to encrypting state
- activate_config: Activate encrypting configuration
- discard: Discard pending configuration
- add_column: Configure column for encryption
- remove_column: Remove column from encryption
- reload_config: Placeholder for config sync
- config: Query configuration in tabular format

Config module (private):
- config_default: Initialize default config structure
- config_add_table: Add table to configuration
- config_add_column: Add column to table config
- config_add_cast: Set cast type for column
- config_add_index: Add search index to column
- config_match_default: Generate match index defaults

Encrypted types:
- eql_v2_encrypted: Core composite type for encrypted data

Operators:
- eq: Equality comparison helper (internal)
- = operator: Three overloads for encrypted/JSONB comparisons

Coverage: 21 objects documented across 4 files
All include @brief, @param, @return tags
Customer-facing functions include @example tags
Internal functions marked with @internal

Part of: add-doxygen-sql-comments plan
Phase: 2 (Core modules - checkpoint 1/7)

Author: tobyhede

src/config/functions.sql

@@ -2,16 +2,33 @@
 -- REQUIRE: src/config/functions_private.sql
 -- REQUIRE: src/encrypted/functions.sql
 
-
--- Customer-facing configuration functions
--- Depends on private functions for implemenation
---
---
-
---
--- Adds an index term to the configuration
---
-
+--! @brief Add a search index configuration for an encrypted column
+--!
+--! Configures a searchable encryption index (unique, match, ore, or ste_vec) on an
+--! encrypted column. Creates or updates the pending configuration, then migrates
+--! and activates it unless migrating flag is set.
+--!
+--! @param table_name Text Name of the table containing the column
+--! @param column_name Text Name of the column to configure
+--! @param index_name Text Type of index ('unique', 'match', 'ore', 'ste_vec')
+--! @param cast_as Text PostgreSQL type for decrypted values (default: 'text')
+--! @param opts JSONB Index-specific options (default: '{}')
+--! @param migrating Boolean Skip auto-migration if true (default: false)
+--! @return JSONB Updated configuration object
+--! @throws Exception if index already exists for this column
+--! @throws Exception if cast_as is not a valid type
+--!
+--! @example
+--! -- Add unique index for exact-match searches
+--! SELECT eql_v2.add_search_config('users', 'email', 'unique');
+--!
+--! -- Add match index for LIKE searches with custom token length
+--! SELECT eql_v2.add_search_config('posts', 'content', 'match', 'text',
+--!   '{"token_filters": [{"kind": "downcase"}], "tokenizer": {"kind": "ngram", "token_length": 3}}'
+--! );
+--!
+--! @see eql_v2.add_column
+--! @see eql_v2.remove_search_config
 CREATE FUNCTION eql_v2.add_search_config(table_name text, column_name text, index_name text, cast_as text DEFAULT 'text', opts jsonb DEFAULT '{}', migrating boolean DEFAULT false)
   RETURNS jsonb
 
@@ -68,8 +85,27 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Remove a search index configuration from an encrypted column
+--!
+--! Removes a previously configured search index from an encrypted column.
+--! Updates the pending configuration, then migrates and activates it
+--! unless migrating flag is set.
+--!
+--! @param table_name Text Name of the table containing the column
+--! @param column_name Text Name of the column
+--! @param index_name Text Type of index to remove
+--! @param migrating Boolean Skip auto-migration if true (default: false)
+--! @return JSONB Updated configuration object
+--! @throws Exception if no active or pending configuration exists
+--! @throws Exception if table is not configured
+--! @throws Exception if column is not configured
+--!
+--! @example
+--! -- Remove match index from column
+--! SELECT eql_v2.remove_search_config('posts', 'content', 'match');
+--!
+--! @see eql_v2.add_search_config
+--! @see eql_v2.modify_search_config
 CREATE FUNCTION eql_v2.remove_search_config(table_name text, column_name text, index_name text, migrating boolean DEFAULT false)
   RETURNS jsonb
 AS $$
@@ -118,8 +154,28 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Modify a search index configuration for an encrypted column
+--!
+--! Updates an existing search index configuration by removing and re-adding it
+--! with new options. Convenience function that combines remove and add operations.
+--!
+--! @param table_name Text Name of the table containing the column
+--! @param column_name Text Name of the column
+--! @param index_name Text Type of index to modify
+--! @param cast_as Text PostgreSQL type for decrypted values (default: 'text')
+--! @param opts JSONB New index-specific options (default: '{}')
+--! @param migrating Boolean Skip auto-migration if true (default: false)
+--! @return JSONB Updated configuration object
+--! @throws Exception if index does not exist
+--!
+--! @example
+--! -- Change match index tokenizer settings
+--! SELECT eql_v2.modify_search_config('posts', 'content', 'match', 'text',
+--!   '{"tokenizer": {"kind": "ngram", "token_length": 4}}'
+--! );
+--!
+--! @see eql_v2.add_search_config
+--! @see eql_v2.remove_search_config
 CREATE FUNCTION eql_v2.modify_search_config(table_name text, column_name text, index_name text, cast_as text DEFAULT 'text', opts jsonb DEFAULT '{}', migrating boolean DEFAULT false)
   RETURNS jsonb
 AS $$
@@ -129,20 +185,23 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
---
---
--- Marks the currently `pending` configuration as `encrypting`.
---
--- Validates the database schema and raises an exception if the configured columns are not `cs_encrypted_v2` type.
---
--- Accepts an optional `force` parameter.
--- If `force` is `true`, the schema validation is skipped.
---
--- Raises an exception if the configuration is already `encrypting` or if there is no `pending` configuration to encrypt.
---
-
+--! @brief Migrate pending configuration to encrypting state
+--!
+--! Transitions the pending configuration to encrypting state, validating that
+--! all configured columns have encrypted target columns ready. This is part of
+--! the configuration lifecycle: pending → encrypting → active.
+--!
+--! @return Boolean True if migration succeeds
+--! @throws Exception if encryption already in progress
+--! @throws Exception if no pending configuration exists
+--! @throws Exception if configured columns lack encrypted targets
+--!
+--! @example
+--! -- Manually migrate configuration (normally done automatically)
+--! SELECT eql_v2.migrate_config();
+--!
+--! @see eql_v2.activate_config
+--! @see eql_v2.add_column
 CREATE FUNCTION eql_v2.migrate_config()
   RETURNS boolean
 AS $$
@@ -165,8 +224,21 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Activate encrypting configuration
+--!
+--! Transitions the encrypting configuration to active state, making it the
+--! current operational configuration. Marks previous active configuration as
+--! inactive. Final step in configuration lifecycle: pending → encrypting → active.
+--!
+--! @return Boolean True if activation succeeds
+--! @throws Exception if no encrypting configuration exists to activate
+--!
+--! @example
+--! -- Manually activate configuration (normally done automatically)
+--! SELECT eql_v2.activate_config();
+--!
+--! @see eql_v2.migrate_config
+--! @see eql_v2.add_column
 CREATE FUNCTION eql_v2.activate_config()
   RETURNS boolean
 AS $$
@@ -182,8 +254,20 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Discard pending configuration
+--!
+--! Deletes the pending configuration without applying changes. Use this to
+--! abandon configuration changes before they are migrated and activated.
+--!
+--! @return Boolean True if discard succeeds
+--! @throws Exception if no pending configuration exists to discard
+--!
+--! @example
+--! -- Discard uncommitted configuration changes
+--! SELECT eql_v2.discard();
+--!
+--! @see eql_v2.add_column
+--! @see eql_v2.add_search_config
 CREATE FUNCTION eql_v2.discard()
   RETURNS boolean
 AS $$
@@ -197,8 +281,28 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Configure a column for encryption
+--!
+--! Adds a column to the encryption configuration, making it eligible for
+--! encrypted storage and search indexes. Creates or updates pending configuration,
+--! adds encrypted constraint, then migrates and activates unless migrating flag is set.
+--!
+--! @param table_name Text Name of the table containing the column
+--! @param column_name Text Name of the column to encrypt
+--! @param cast_as Text PostgreSQL type to cast decrypted values (default: 'text')
+--! @param migrating Boolean Skip auto-migration if true (default: false)
+--! @return JSONB Updated configuration object
+--! @throws Exception if column already configured for encryption
+--!
+--! @example
+--! -- Configure email column for encryption
+--! SELECT eql_v2.add_column('users', 'email', 'text');
+--!
+--! -- Configure age column with integer casting
+--! SELECT eql_v2.add_column('users', 'age', 'int');
+--!
+--! @see eql_v2.add_search_config
+--! @see eql_v2.remove_column
 CREATE FUNCTION eql_v2.add_column(table_name text, column_name text, cast_as text DEFAULT 'text', migrating boolean DEFAULT false)
   RETURNS jsonb
 AS $$
@@ -242,8 +346,26 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Remove a column from encryption configuration
+--!
+--! Removes a column from the encryption configuration, including all associated
+--! search indexes. Removes encrypted constraint, updates pending configuration,
+--! then migrates and activates unless migrating flag is set.
+--!
+--! @param table_name Text Name of the table containing the column
+--! @param column_name Text Name of the column to remove
+--! @param migrating Boolean Skip auto-migration if true (default: false)
+--! @return JSONB Updated configuration object
+--! @throws Exception if no active or pending configuration exists
+--! @throws Exception if table is not configured
+--! @throws Exception if column is not configured
+--!
+--! @example
+--! -- Remove email column from encryption
+--! SELECT eql_v2.remove_column('users', 'email');
+--!
+--! @see eql_v2.add_column
+--! @see eql_v2.remove_search_config
 CREATE FUNCTION eql_v2.remove_column(table_name text, column_name text, migrating boolean DEFAULT false)
   RETURNS jsonb
 AS $$
@@ -305,19 +427,38 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Reload configuration from CipherStash Proxy
+--!
+--! Placeholder function for reloading configuration from the CipherStash Proxy.
+--! Currently returns NULL without side effects.
+--!
+--! @return Void
+--!
+--! @note This function may be used for configuration synchronization in future versions
 CREATE FUNCTION eql_v2.reload_config()
   RETURNS void
 LANGUAGE sql STRICT PARALLEL SAFE
 BEGIN ATOMIC
   RETURN NULL;
 END;
 
-
--- A convenience function to return the configuration in a tabular format, allowing for easier filtering, and querying.
--- Query using `SELECT * FROM cs_config();`
---
+--! @brief Query encryption configuration in tabular format
+--!
+--! Returns the active encryption configuration as a table for easier querying
+--! and filtering. Shows all configured tables, columns, cast types, and indexes.
+--!
+--! @return TABLE Contains configuration state, relation name, column name, cast type, and indexes
+--!
+--! @example
+--! -- View all encrypted columns
+--! SELECT * FROM eql_v2.config();
+--!
+--! -- Find all columns with match indexes
+--! SELECT relation, col_name FROM eql_v2.config()
+--! WHERE indexes ? 'match';
+--!
+--! @see eql_v2.add_column
+--! @see eql_v2.add_search_config
 CREATE FUNCTION eql_v2.config() RETURNS TABLE (
     state eql_v2_configuration_state,
     relation text,