Skip to content

Commit 01ab2f8

Browse files
tobyhedetobyhede
committed
docs(sql): ensure Doxygen comments included in generated version.sql
- Updated version.template to avoid awkward $RELEASE_VERSION text replacement in docs - Changed @file tag from version.template to version.sql (the generated file) - Simplified documentation to avoid version string in prose - Added comment in build.sh clarifying Doxygen comment preservation - Added validation scripts for documentation quality assurance: - check-doc-coverage.sh: Reports documentation coverage (100%) - validate-documented-sql.sh: Validates SQL syntax - validate-required-tags.sh: Checks for required @brief, @param, @return tags The sed command in build.sh already preserves all Doxygen comments from the template, ensuring the generated version.sql is fully documented.
1 parent d4c2257 commit 01ab2f8

File tree

5 files changed

+237
-6
lines changed

5 files changed

+237
-6
lines changed

‎src/version.template‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,11 @@
44

55
DROP FUNCTION IF EXISTS eql_v2.version();
66

7-
--! @file version.template
8-
--! @brief EQL version reporting template
7+
--! @file version.sql
8+
--! @brief EQL version reporting
99
--!
10-
--! Template file for version.sql. The $RELEASE_VERSION placeholder is
11-
--! replaced during build with the actual release version string.
10+
--! This file is auto-generated from version.template during build.
11+
--! The version string placeholder is replaced with the actual release version.
1212

1313
--! @brief Get EQL library version string
1414
--!
@@ -17,8 +17,7 @@ DROP FUNCTION IF EXISTS eql_v2.version();
1717
--!
1818
--! @return text Version string (e.g., "2.1.0" or "DEV" for development builds)
1919
--!
20-
--! @note This file is a template - version.sql is generated during build
21-
--! @note The $RELEASE_VERSION placeholder is replaced at build time
20+
--! @note Auto-generated during build from version.template
2221
--!
2322
--! @example
2423
--! -- Check installed EQL version

‎tasks/build.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ rm -f src/deps-ordered-supabase.txt
2323

2424

2525
RELEASE_VERSION=${usage_version:-DEV}
26+
# Generate version.sql from template, preserving Doxygen comments
2627
sed "s/\$RELEASE_VERSION/$RELEASE_VERSION/g" src/version.template > src/version.sql
2728

2829

‎tasks/check-doc-coverage.sh‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
#!/bin/bash
2+
# tasks/check-doc-coverage.sh
3+
# Checks documentation coverage for SQL files
4+
5+
set -e
6+
7+
cd "$(dirname "$0")/.."
8+
9+
echo "# SQL Documentation Coverage Report"
10+
echo ""
11+
echo "Generated: $(date)"
12+
echo ""
13+
14+
total_sql_files=0
15+
documented_sql_files=0
16+
17+
# Check .sql files
18+
for file in $(find src -name "*.sql" -not -name "*_test.sql" | sort); do
19+
# Skip auto-generated files
20+
if grep -q "^-- AUTOMATICALLY GENERATED FILE" "$file" 2>/dev/null; then
21+
echo "- $file: ⊘ Auto-generated (skipped)"
22+
continue
23+
fi
24+
25+
total_sql_files=$((total_sql_files + 1))
26+
27+
if grep -q "^--! @brief" "$file" 2>/dev/null; then
28+
echo "- $file: ✓ Documented"
29+
documented_sql_files=$((documented_sql_files + 1))
30+
else
31+
echo "- $file: ✗ No documentation"
32+
fi
33+
done
34+
35+
# Check .template files
36+
total_template_files=0
37+
documented_template_files=0
38+
39+
for file in $(find src -name "*.template" | sort); do
40+
total_template_files=$((total_template_files + 1))
41+
42+
if grep -q "^--! @brief" "$file" 2>/dev/null; then
43+
echo "- $file: ✓ Documented"
44+
documented_template_files=$((documented_template_files + 1))
45+
else
46+
echo "- $file: ✗ No documentation"
47+
fi
48+
done
49+
50+
total_files=$((total_sql_files + total_template_files))
51+
documented_files=$((documented_sql_files + documented_template_files))
52+
53+
echo ""
54+
echo "## Summary"
55+
echo ""
56+
echo "- SQL files: $documented_sql_files/$total_sql_files"
57+
echo "- Template files: $documented_template_files/$total_template_files"
58+
echo "- Total files: $documented_files/$total_files"
59+
60+
if [ $total_files -gt 0 ]; then
61+
coverage=$((documented_files * 100 / total_files))
62+
echo "- Coverage: ${coverage}%"
63+
else
64+
coverage=0
65+
fi
66+
67+
echo ""
68+
69+
if [ $coverage -eq 100 ]; then
70+
echo "✅ 100% documentation coverage achieved!"
71+
exit 0
72+
else
73+
echo "⚠️ Documentation coverage: ${coverage}%"
74+
exit 1
75+
fi

‎tasks/validate-documented-sql.sh‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
#!/bin/bash
2+
# tasks/validate-documented-sql.sh
3+
# Validates SQL syntax for all documented files
4+
5+
set -e
6+
7+
cd "$(dirname "$0")/.."
8+
9+
PGHOST=${PGHOST:-localhost}
10+
PGPORT=${PGPORT:-7432}
11+
PGUSER=${PGUSER:-cipherstash}
12+
PGPASSWORD=${PGPASSWORD:-password}
13+
PGDATABASE=${PGDATABASE:-postgres}
14+
15+
echo "Validating SQL syntax for all documented files..."
16+
echo ""
17+
18+
errors=0
19+
validated=0
20+
21+
for file in $(find src -name "*.sql" -not -name "*_test.sql" | sort); do
22+
echo -n "Validating $file... "
23+
24+
# Capture both stdout and stderr
25+
error_output=$(PGPASSWORD="$PGPASSWORD" psql -h "$PGHOST" -p "$PGPORT" -U "$PGUSER" -d "$PGDATABASE" \
26+
-f "$file" --set ON_ERROR_STOP=1 -q 2>&1) || exit_code=$?
27+
28+
if [ "${exit_code:-0}" -eq 0 ]; then
29+
echo "✓"
30+
validated=$((validated + 1))
31+
else
32+
echo "✗ SYNTAX ERROR"
33+
echo " Error in: $file"
34+
echo " Details:"
35+
echo "$error_output" | tail -10 | sed 's/^/ /'
36+
echo ""
37+
errors=$((errors + 1))
38+
fi
39+
exit_code=0
40+
done
41+
42+
echo ""
43+
echo "Validation complete:"
44+
echo " Validated: $validated"
45+
echo " Errors: $errors"
46+
47+
if [ $errors -gt 0 ]; then
48+
echo ""
49+
echo "❌ Validation failed with $errors errors"
50+
exit 1
51+
else
52+
echo ""
53+
echo "✅ All SQL files validated successfully"
54+
exit 0
55+
fi

‎tasks/validate-required-tags.sh‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
#!/bin/bash
2+
# tasks/validate-required-tags.sh
3+
# Validates that required Doxygen tags are present
4+
5+
set -e
6+
7+
cd "$(dirname "$0")/.."
8+
9+
echo "Validating required Doxygen tags..."
10+
echo ""
11+
12+
errors=0
13+
warnings=0
14+
15+
for file in $(find src -name "*.sql" -not -name "*_test.sql"); do
16+
# For each CREATE FUNCTION, check tags
17+
functions=$(grep -n "^CREATE FUNCTION" "$file" 2>/dev/null | cut -d: -f1 || echo "")
18+
19+
for line_no in $functions; do
20+
# Find comment block above function (search backwards max 50 lines)
21+
start=$((line_no - 50))
22+
[ "$start" -lt 1 ] && start=1
23+
24+
comment_block=$(sed -n "${start},${line_no}p" "$file" | grep "^--!" | tail -20)
25+
26+
function_sig=$(sed -n "${line_no}p" "$file")
27+
function_name=$(echo "$function_sig" | grep -oP 'CREATE FUNCTION \K[^\(]+' | xargs || echo "unknown")
28+
29+
# Check for @brief
30+
if ! echo "$comment_block" | grep -q "@brief"; then
31+
echo "ERROR: $file:$line_no $function_name - Missing @brief"
32+
errors=$((errors + 1))
33+
fi
34+
35+
# Check for @param (if function has parameters)
36+
if echo "$function_sig" | grep -q "(" && \
37+
! echo "$function_sig" | grep -q "()"; then
38+
if ! echo "$comment_block" | grep -q "@param"; then
39+
echo "WARNING: $file:$line_no $function_name - Missing @param"
40+
warnings=$((warnings + 1))
41+
fi
42+
fi
43+
44+
# Check for @return (if function returns something other than void)
45+
if ! echo "$function_sig" | grep -qi "RETURNS void"; then
46+
if ! echo "$comment_block" | grep -q "@return"; then
47+
echo "ERROR: $file:$line_no $function_name - Missing @return"
48+
errors=$((errors + 1))
49+
fi
50+
fi
51+
done
52+
done
53+
54+
# Also check template files
55+
for file in $(find src -name "*.template"); do
56+
functions=$(grep -n "^CREATE FUNCTION" "$file" 2>/dev/null | cut -d: -f1 || echo "")
57+
58+
for line_no in $functions; do
59+
start=$((line_no - 50))
60+
[ "$start" -lt 1 ] && start=1
61+
62+
comment_block=$(sed -n "${start},${line_no}p" "$file" | grep "^--!" | tail -20)
63+
64+
function_sig=$(sed -n "${line_no}p" "$file")
65+
function_name=$(echo "$function_sig" | grep -oP 'CREATE FUNCTION \K[^\(]+' | xargs || echo "unknown")
66+
67+
if ! echo "$comment_block" | grep -q "@brief"; then
68+
echo "ERROR: $file:$line_no $function_name - Missing @brief"
69+
errors=$((errors + 1))
70+
fi
71+
72+
if echo "$function_sig" | grep -q "(" && \
73+
! echo "$function_sig" | grep -q "()"; then
74+
if ! echo "$comment_block" | grep -q "@param"; then
75+
echo "WARNING: $file:$line_no $function_name - Missing @param"
76+
warnings=$((warnings + 1))
77+
fi
78+
fi
79+
80+
if ! echo "$function_sig" | grep -qi "RETURNS void"; then
81+
if ! echo "$comment_block" | grep -q "@return"; then
82+
echo "ERROR: $file:$line_no $function_name - Missing @return"
83+
errors=$((errors + 1))
84+
fi
85+
fi
86+
done
87+
done
88+
89+
echo ""
90+
echo "Validation summary:"
91+
echo " Errors: $errors"
92+
echo " Warnings: $warnings"
93+
echo ""
94+
95+
if [ "$errors" -gt 0 ]; then
96+
echo "❌ Validation failed with $errors errors"
97+
exit 1
98+
else
99+
echo "✅ All required tags present"
100+
exit 0
101+
fi

0 commit comments

Comments
 (0)