Add doxygen docs comments #148
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add comprehensive Doxygen comments across all SQL modules: **Phase 1**: Documentation standards, templates, and tooling **Phase 2**: Config module, encrypted types, operators, comparison functions **Phase 3**: Index implementations (Blake3, HMAC-256, Bloom Filter, ORE, STE) **Phase 4**: JSONB functions, config schema, lifecycle management, utilities This commit consolidates all documentation work from continue-doxygen-sql-comments branch (commit a398dc8) into a clean history. Includes documentation for 52+ SQL files with complete @brief, @param, @return, @throws, @example, and @see tags following established standards. Source branch: continue-doxygen-sql-comments (pre-merge state) Original commits: f41981a..a398dc8 (19 commits)
Add complete Doxygen generation and validation infrastructure: **Configuration:** - Doxyfile - Doxygen configuration for HTML/LaTeX output - CLAUDE.md - Documentation standards and guidelines **Validation Scripts:** - tasks/check-doc-coverage.sh - Verify documentation coverage - tasks/validate-required-tags.sh - Ensure required tags present - tasks/doxygen-filter.sh - SQL-to-C++ comment filter for Doxygen **Mise Tasks:** - docs:generate - Generate API documentation - docs:validate - Run coverage and tag validation Source: phase-4-doxygen branch (commits 2e53216, ee96e15, e8debb0, etc.)
Add validate-docs job to GitHub Actions workflow: - Runs documentation coverage and tag validation - Executes before test job (dependency) - Uses mise run docs:validate Also update README.md with Documentation section explaining: - How to install Doxygen - How to generate documentation (mise run docs:generate) - Documentation standards overview Source: phase-4-doxygen (commits 1264b71, 5e37aca)
Document version.template to achieve 100% documentation coverage: - Add @file tag for version.sql (the generated file) - Document eql_v2.version() function with @brief, @return, @example - Add @note explaining auto-generation from template - Fixes CI validation error for version.template Source: phase-4-doxygen (commits d4c2257, 01ab2f8)
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
Fix functional regressions from using continue-doxygen-sql-comments source: - src/config/functions.sql: Uncomment add_encrypted_constraint call - src/config/config_test.sql: Better test documentation - src/encrypted/constraints_test.sql: Enhanced test documentation - src/encrypted/functions.sql: Improved documentation - src/encryptindex/functions.sql: Documentation improvements - src/encryptindex/functions_test.sql: Test documentation - src/jsonb/functions.sql: Better function documentation These files use the phase-4-doxygen versions which branched from clean main and have correct code + better Phase 4 documentation. Source: phase-4-doxygen (clean main branch + Phase 4 docs)
Add check to skip auto-generated files (with '-- AUTOMATICALLY GENERATED FILE' marker) in validate-required-tags.sh, matching check-doc-coverage.sh behavior. This fixes validation errors for src/version.sql which is generated during build from src/version.template (which is properly documented). Validation now correctly: - Skips version.sql (auto-generated, in .gitignore) - Validates version.template (source with documentation) - Achieves 100% coverage without errors
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
docs:generateanddocs:validatedocs:validate