Skip to content

Commit 4ecfa67

Browse files
tobyhedetobyhede
committed
Merge phase-4-doxygen infrastructure into continue-doxygen-sql-comments
Combines: - Complete Phase 1-4 Doxygen documentation from continue-doxygen-sql-comments - Infrastructure from phase-4-doxygen: * Doxyfile configuration * Documentation validation scripts (check-doc-coverage.sh, validate-required-tags.sh) * CI integration updates * CLAUDE.md with Doxygen standards Resolution strategy: Kept documentation from continue-doxygen-sql-comments (has complete Phase 1-4 work + subsequent fixes) and added infrastructure files from phase-4-doxygen. This creates a complete branch with all documentation and tooling.
2 parents a398dc8 + b4d6b4d commit 4ecfa67

40 files changed

+6192
-0
lines changed

‎2025-10-27-phase-4-review.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Code Review - Phase 4 Documentation (2025-10-27)
2+
3+
## Status: APPROVED
4+
5+
## BLOCKING (Must Fix Before Merge)
6+
7+
None
8+
9+
## NON-BLOCKING (May Be Deferred)
10+
11+
**Minor: version.sql file header inconsistency:**
12+
- Description: The file header says "AUTOMATICALLY GENERATED FILE" but we manually added Doxygen comments to it. The comments should clarify that while the version string is auto-generated, the documentation is maintained manually.
13+
- Location: src/version.sql:1-12
14+
- Action: Consider adding a note: `@note Version string auto-generated at build time, documentation maintained manually`
15+
16+
## Highlights
17+
18+
**Comprehensive and Systematic Documentation:**
19+
- What: Added Doxygen documentation to 32 files across Phase 4 with consistent structure and formatting. Every function includes `@brief`, appropriate parameter documentation, return value description, and relevant notes.
20+
- Location: All Phase 4 files (encrypted/, config/, jsonb/, encryptindex/, root utilities)
21+
22+
**Excellent Use of Cross-References:**
23+
- What: Documentation includes `@see` tags linking related functions, creating a navigable documentation graph
24+
- Location: Examples in src/config/constraints.sql:151-154 (comprehensive CHECK constraint with @see references to all validation functions)
25+
26+
**Clear Distinction of Internal vs Public APIs:**
27+
- What: Consistent use of `@internal` tags to mark implementation details vs customer-facing functions
28+
- Location: All constraint validation functions properly marked internal (src/config/constraints.sql), while customer-facing functions like `jsonb_path_query` include examples
29+
30+
**Practical Examples for Customer-Facing Functions:**
31+
- What: Customer-facing functions include concrete `@example` sections showing actual usage
32+
- Location: src/jsonb/functions.sql:117-119 (jsonb_path_query example), src/config/constraints.sql:121-123 (check_encrypted constraint example)
33+
34+
**Context-Rich Documentation:**
35+
- What: `@note` tags provide important context about behavior, usage patterns, and edge cases
36+
- Location: src/common.sql:24 (constant-time comparison security note), src/config/indexes.sql:12 (explains partial index efficiency)
37+
38+
**File-Level Documentation:**
39+
- What: Each module includes comprehensive `@file` documentation explaining the module's purpose and what it contains
40+
- Location: src/jsonb/functions.sql:4-14, src/encryptindex/functions.sql:1-11
41+
42+
## Test Results
43+
- Status: **PASS** ✅
44+
- Details: All 40+ test files passed successfully. Build completed without errors.
45+
```
46+
###############################################
47+
# ✅ALL TESTS PASSED
48+
###############################################
49+
```
50+
51+
## Check Results
52+
- Status: Not run (no `mise run check` task in this project)
53+
- Details: N/A - project uses tests only for verification
54+
55+
## Summary
56+
57+
Phase 4 documentation work adds 718 lines of high-quality Doxygen comments (+555 net lines) across 13 critical SQL files:
58+
59+
**Documented Modules:**
60+
- **Operators Infrastructure** (3 files): compare.sql, order_by.sql, operator_class.sql
61+
- **Encrypted Supporting Files** (4 files): aggregates.sql, casts.sql, compare.sql, constraints.sql
62+
- **JSONB Functions** (15 functions): Path query operations and array manipulation
63+
- **Config Schema** (4 files): types.sql, tables.sql, indexes.sql, constraints.sql
64+
- **Encryptindex Functions** (7 functions): Configuration lifecycle management
65+
- **Root Utilities** (4 files): common.sql, crypto.sql, schema.sql, version.sql
66+
67+
**Quality Indicators:**
68+
- ✅ Consistent Doxygen formatting across all files
69+
- ✅ Appropriate use of tags (@brief, @param, @return, @throws, @note, @see, @internal, @example)
70+
- ✅ Clear distinction between internal and public APIs
71+
- ✅ Practical examples for customer-facing functions
72+
- ✅ Cross-references create navigable documentation
73+
- ✅ File-level documentation provides module context
74+
- ✅ All tests pass - documentation doesn't break functionality
75+
- ✅ No security or correctness issues introduced
76+
77+
## Next Steps
78+
79+
1. ✅ Review complete - APPROVED
80+
2. Commit Phase 4 documentation with conventional commit message
81+
3. Continue to Phase 5 (if applicable) or complete documentation project

‎CLAUDE.md‎

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Development Commands
6+
7+
This project uses `mise` for task management. Common commands:
8+
9+
- `mise run build` (alias: `mise r b`) - Build SQL into single release file
10+
- `mise run test` (alias: `mise r test`) - Build, reset and run tests
11+
- `mise run postgres:up` - Start PostgreSQL container
12+
- `mise run postgres:down` - Stop PostgreSQL containers
13+
- `mise run reset` - Reset database state
14+
- `mise run clean` (alias: `mise r k`) - Clean release files
15+
- `mise run docs:generate` - Generate API documentation (requires doxygen)
16+
- `mise run docs:validate` - Validate documentation coverage and tags
17+
18+
### Testing
19+
- Run all tests: `mise run test`
20+
- Run specific test: `mise run test --test <test_name>`
21+
- Run tests against specific PostgreSQL version: `mise run test --postgres 14|15|16|17`
22+
- Tests are located in `*_test.sql` files alongside source code
23+
24+
### Build System
25+
- Dependencies are resolved using `-- REQUIRE:` comments in SQL files
26+
- Build outputs to `release/` directory:
27+
- `cipherstash-encrypt.sql` - Main installer
28+
- `cipherstash-encrypt-supabase.sql` - Supabase-compatible installer
29+
- `cipherstash-encrypt-uninstall.sql` - Uninstaller
30+
31+
## Project Architecture
32+
33+
This is the **Encrypt Query Language (EQL)** - a PostgreSQL extension for searchable encryption. Key architectural components:
34+
35+
### Core Structure
36+
- **Schema**: All EQL functions/types are in `eql_v2` PostgreSQL schema
37+
- **Main Type**: `eql_v2_encrypted` - composite type for encrypted columns (stored as JSONB)
38+
- **Configuration**: `eql_v2_configuration` table tracks encryption configs
39+
- **Index Types**: Various encrypted index types (blake3, hmac_256, bloom_filter, ore variants)
40+
41+
### Directory Structure
42+
- `src/` - Modular SQL components with dependency management
43+
- `src/encrypted/` - Core encrypted column type implementation
44+
- `src/operators/` - SQL operators for encrypted data comparisons
45+
- `src/config/` - Configuration management functions
46+
- `src/blake3/`, `src/hmac_256/`, `src/bloom_filter/`, `src/ore_*` - Index implementations
47+
- `tasks/` - mise task scripts
48+
- `tests/` - Test files (PostgreSQL 14-17 support)
49+
- `release/` - Generated SQL installation files
50+
51+
### Key Concepts
52+
- **Dependency System**: SQL files declare dependencies via `-- REQUIRE:` comments
53+
- **Encrypted Data**: Stored as JSONB payloads with metadata
54+
- **Index Terms**: Transient types for search operations (blake3, hmac_256, etc.)
55+
- **Operators**: Support comparisons between encrypted and plain JSONB data
56+
- **CipherStash Proxy**: Required for encryption/decryption operations
57+
58+
### Testing Infrastructure
59+
- Tests run against PostgreSQL 14, 15, 16, 17 using Docker containers
60+
- Container configuration in `tests/docker-compose.yml`
61+
- Test helpers in `tests/test_helpers.sql`
62+
- Database connection: `localhost:7432` (cipherstash/password)
63+
- **Rust/SQLx Tests**: Modern test framework in `tests/sqlx/` (see README there)
64+
65+
## Project Learning & Retrospectives
66+
67+
Valuable lessons and insights from completed work:
68+
69+
- **SQLx Test Migration (2025-10-24)**: See `docs/retrospectives/2025-10-24-sqlx-migration-retrospective.md`
70+
- Migrated 40 SQL assertions to Rust/SQLx (100% coverage)
71+
- Key insights: Blake3 vs HMAC differences, batch-review pattern effectiveness, coverage metric definitions
72+
- Lessons: TDD catches setup issues, infrastructure investment pays off, code review after each batch prevents compound errors
73+
74+
## Documentation Standards
75+
76+
### Doxygen Comments
77+
78+
All SQL functions and types must be documented using Doxygen-style comments:
79+
80+
- **Comment Style**: Use `--!` prefix for Doxygen comments (not `--`)
81+
- **Required Tags**:
82+
- `@brief` - Short description (required for all functions/files)
83+
- `@param` - Parameter description (required for functions with parameters)
84+
- `@return` - Return value description (required for functions with non-void returns)
85+
- **Optional Tags**:
86+
- `@throws` - Exception conditions
87+
- `@note` - Important notes or caveats
88+
- `@warning` - Warning messages (e.g., for DDL-executing functions)
89+
- `@see` - Cross-references to related functions
90+
- `@example` - Usage examples
91+
- `@internal` - Mark internal/private functions
92+
- `@file` - File-level documentation
93+
94+
### Documentation Example
95+
96+
```sql
97+
--! @brief Create encrypted index configuration
98+
--!
99+
--! Initializes a new encrypted index configuration for a table column.
100+
--! The configuration tracks encryption settings and index types.
101+
--!
102+
--! @param p_table_name text Table name (schema-qualified)
103+
--! @param p_column_name text Column name to encrypt
104+
--! @param p_index_type text Type of encrypted index (blake3, hmac_256, etc.)
105+
--!
106+
--! @return uuid Configuration ID for the created index
107+
--!
108+
--! @throws unique_violation If configuration already exists for this column
109+
--!
110+
--! @note This function executes DDL and modifies database schema
111+
--! @see eql_v2.activate_encrypted_index
112+
--!
113+
--! @example
114+
--! -- Create blake3 index configuration
115+
--! SELECT eql_v2.create_encrypted_index(
116+
--! 'public.users',
117+
--! 'email',
118+
--! 'blake3'
119+
--! );
120+
CREATE FUNCTION eql_v2.create_encrypted_index(...)
121+
```
122+
123+
### Validation Tools
124+
125+
Verify documentation quality:
126+
127+
```bash
128+
# Using mise (recommended - validates coverage and tags)
129+
mise run docs:validate
130+
131+
# Or run individual scripts directly
132+
tasks/check-doc-coverage.sh # Check 100% coverage
133+
tasks/validate-required-tags.sh # Verify @brief, @param, @return tags
134+
tasks/validate-documented-sql.sh # Validate SQL syntax (requires database)
135+
```
136+
137+
### Template Files
138+
139+
Template files (e.g., `version.template`) must be documented. The Doxygen comments are automatically included in generated files during build.
140+
141+
## Development Notes
142+
143+
- SQL files are modular - put operator wrappers in `operators.sql`, implementation in `functions.sql`
144+
- All SQL files must have `-- REQUIRE:` dependency declarations
145+
- Test files end with `_test.sql` and live alongside source files
146+
- Build system uses `tsort` to resolve dependency order
147+
- Supabase build excludes operator classes (not supported)
148+
- **Documentation**: All functions/types must have Doxygen comments (see Documentation Standards above)

0 commit comments

Comments
 (0)