better doxygen before final iteration

Author: maureeungaro

ci/create_doxygen.sh

@@ -1,8 +1,10 @@
 #!/usr/bin/env zsh
+# File: ci/create_doxygen.sh
+#
 # Purpose:
-#   - Generate an up-to-date base Doxyfile from `doxygen -g` (cached per doxygen version)
-#   - Sanitize that base deterministically on every run (fixes template multi-line lists)
-#   - Emit a tiny per-module Doxyfile that @INCLUDEs that sanitized base
+#   - Generate a fresh base Doxyfile from `doxygen -g` on every run (NO .cache usage)
+#   - Sanitize that base deterministically (fixes template multi-line lists)
+#   - Emit a per-module Doxyfile that INLINES the sanitized base + module overrides
 #
 # Usage:
 #   ./ci/create_doxygen.sh <module_name>
@@ -15,14 +17,9 @@ die() { print -u2 -- "ERROR: $*"; exit 2; }
 mod="$1"
 
 script_dir="${0:A:h}"
-cache_dir="$script_dir/doxygen/.cache"
-mkdir -p "$cache_dir"
-
-base_pure="$cache_dir/Doxyfile.pure"
-base_file="$cache_dir/Doxyfile.base"
-ver_file="$cache_dir/doxygen.version"
 
-doxver="$(doxygen --version)"
+doxver="$(doxygen --version 2>/dev/null || true)"
+[[ -n "$doxver" ]] || die "doxygen not found in PATH"
 
 # Portable in-place sed (BSD/macOS vs GNU)
 inplace_sed() {
@@ -35,30 +32,33 @@ inplace_sed() {
   fi
 }
 
-
 # Replace a doxygen list key that may be written as a multi-line block:
 #   KEY = *.a \
 #         *.b \
 # with a single-line canonical:
 #   KEY = value
 #
-# We remove the KEY line and its following "indented *..." continuation lines,
-# then append the canonical KEY line. Appending is semantically fine for doxygen.
+# Strategy:
+#   - Remove KEY line and continuation lines that follow it
+#   - Append canonical KEY line at end (Doxygen accepts last-one-wins)
 replace_doxy_list_key_single_line() {
   local file="$1"
   local key="$2"
   local value="$3"
 
   # Remove existing KEY line + template continuation lines that follow it.
+  # Continuations from `doxygen -g` are often indented and may start with "*.ext".
   awk -v key="^"key"[[:space:]]*=" '
     BEGIN{skip=0}
-    $0 ~ key { skip=1; next }                   # drop the KEY = ... line
-    skip && $0 ~ /^[[:space:]]+\*/ { next }     # drop indented "*.ext \" lines
-    skip { skip=0 }                             # first non-continuation after block
+    $0 ~ key { skip=1; next }                       # drop the KEY = ... line
+    skip && $0 ~ /^[[:space:]]+\*/ { next }         # drop indented "*..." lines
+    skip && $0 ~ /^[[:space:]]+\*\.[^[:space:]]/ { next }  # (extra defensive)
+    skip && $0 ~ /^[[:space:]]+[^#[:space:]].*\\$/ { next } # drop generic "\" continuation lines
+    skip { skip=0 }                                 # first non-continuation after block
     { print }
   ' "$file" > "$file.tmp" && mv "$file.tmp" "$file"
 
-  # Defensive: remove any stray KEY lines that might still exist (shouldn't).
+  # Defensive: remove any stray KEY lines that might still exist.
   if grep -qE "^${key}[[:space:]]*=" "$file"; then
     inplace_sed "/^${key}[[:space:]]*=/d" "$file"
   fi
@@ -88,7 +88,6 @@ sanitize_base() {
   inplace_sed 's|^QUIET[[:space:]]*=.*|QUIET                   = YES|g' "$f"
   inplace_sed 's|^WARNINGS[[:space:]]*=.*|WARNINGS                = YES|g' "$f"
 
-
   replace_doxy_list_key_single_line "$f" "FILE_PATTERNS" \
     "*.h *.hh *.hpp *.hxx *.c *.cc *.cpp *.cxx *.C *.H"
 
@@ -106,34 +105,29 @@ sanitize_base() {
   inplace_sed '/^HTML_OUTPUT[[:space:]]*=/d' "$f"
   inplace_sed '/^GENERATE_TAGFILE[[:space:]]*=/d' "$f"
   inplace_sed '/^TAGFILES[[:space:]]*=/d' "$f"
-}
 
-# ---- (re)generate base if missing or doxygen version changed ----
-need_regen=0
-if [[ ! -f "$base_pure" || ! -f "$base_file" || ! -f "$ver_file" ]]; then
-  need_regen=1
-elif [[ "$(cat "$ver_file")" != "$doxver" ]]; then
-  need_regen=1
-fi
+  # Defensive: remove any stray lines that start with "*" (cause: broken multi-line list blocks)
+  inplace_sed '/^[[:space:]]*\*/d' "$f"
+}
 
-if (( need_regen )); then
-  print -- " [create_doxygen] Generating base for doxygen $doxver"
-  doxygen -g "$base_pure" >/dev/null 2>&1
-  cp -f "$base_pure" "$base_file"
-  print -- "$doxver" > "$ver_file"
-fi
+# ---- Generate fresh base every run (no .cache usage) ----
+tmp_pure="$(mktemp "${TMPDIR:-/tmp}/Doxyfile.pure.XXXXXX")"
+tmp_base="$(mktemp "${TMPDIR:-/tmp}/Doxyfile.base.XXXXXX")"
+cleanup() { rm -f -- "$tmp_pure" "$tmp_base"; }
+trap cleanup EXIT
 
-# Always sanitize (fixes stale/broken cache contents too)
-[[ -f "$base_file" ]] || die "Missing base file '$base_file'"
-sanitize_base "$base_file"
+print -- " [create_doxygen] Generating base for doxygen $doxver"
+doxygen -g "$tmp_pure" >/dev/null 2>&1
+cp -f "$tmp_pure" "$tmp_base"
 
-# Emit tiny module Doxyfile that includes the generated base.
-# Use absolute path so it works regardless of where the module lives.
-base_abs="$base_file"
+sanitize_base "$tmp_base"
 
-cat > Doxyfile <<EOF
-@INCLUDE = $base_abs
+# Emit a module Doxyfile by inlining the sanitized base, then overriding.
+{
+  cat "$tmp_base"
+  cat <<EOF
 
+# ---- module overrides ----
 PROJECT_NAME              = "$mod"
 INPUT                     = .
 OUTPUT_DIRECTORY          = ../pages
@@ -143,6 +137,7 @@ HTML_EXTRA_STYLESHEET     = mydoxygen.css
 
 # TAGFILES is injected by ci/doxygen.sh in pass 2
 EOF
+} > Doxyfile
 
 # Optional: keep local copy for debugging/inspection
 cp -f Doxyfile DoxyfilePure 2>/dev/null || true

ci/doxygen.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env zsh
+# File: ci/doxygen.sh
+#
 # Purpose: build doxygen docs per module with cross-references (2-pass: TAGs then HTML)
 
 set -euo pipefail
@@ -12,8 +14,6 @@ doc_modules=(
 script_dir="${0:A:h}"
 pages_dir="pages"
 
-
-
 usage() {
   cat <<'EOF'
 Usage:
@@ -115,7 +115,14 @@ for m in $modules_to_build; do
   "$script_dir/create_doxygen.sh" "$m"
   [[ -f Doxyfile ]] || die "Missing Doxyfile in '$moddir'"
 
-  inplace_sed 's|^GENERATE_HTML[[:space:]]*=.*|GENERATE_HTML              = NO|g' Doxyfile
+  # Ensure TAG pass doesn't emit HTML
+  if grep -qE '^GENERATE_HTML[[:space:]]*=' Doxyfile; then
+    inplace_sed 's|^GENERATE_HTML[[:space:]]*=.*|GENERATE_HTML              = NO|g' Doxyfile
+  else
+    print -- 'GENERATE_HTML              = NO' >> Doxyfile
+  fi
+
+  # Ensure TAGFILES isn't present in pass 1
   inplace_sed '/^TAGFILES\b/d' Doxyfile
 
   doxygen Doxyfile
@@ -137,7 +144,14 @@ for m in $modules_to_build; do
   "$script_dir/create_doxygen.sh" "$m"
   [[ -f Doxyfile ]] || die "Missing Doxyfile in '$moddir'"
 
-  inplace_sed 's|^GENERATE_HTML[[:space:]]*=.*|GENERATE_HTML              = YES|g' Doxyfile
+  # Ensure HTML is enabled in pass 2
+  if grep -qE '^GENERATE_HTML[[:space:]]*=' Doxyfile; then
+    inplace_sed 's|^GENERATE_HTML[[:space:]]*=.*|GENERATE_HTML              = YES|g' Doxyfile
+  else
+    print -- 'GENERATE_HTML              = YES' >> Doxyfile
+  fi
+
+  # Remove any existing TAGFILES lines before injecting ours
   inplace_sed '/^TAGFILES\b/d' Doxyfile
 
   for other in $doc_modules; do
@@ -151,7 +165,7 @@ for m in $modules_to_build; do
 
   popd >/dev/null
 
-  cp -f "$css_src" "$pages_dir/$m/mydoxygen.css"  2>/dev/null || true
+  cp -f "$css_src" "$pages_dir/$m/mydoxygen.css" 2>/dev/null || true
   [[ -f "$pages_dir/$m/index.html" ]] || die "HTML not produced for $m ($pages_dir/$m/index.html missing)"
   echo
 done

gdata/gdataDoxy.h

@@ -1,7 +1,6 @@
 /**
  * \mainpage GData Library
  *
- * \tableofcontents
  *
  * \section intro_sec Introduction
  * The GData library provides classes and utilities to accumulate simulated “true” information

gdata/meson.build

@@ -0,0 +1,58 @@
+sub_dir_name = meson.current_source_dir().split('/').get(-1)
+internal_deps = ['goptions', 'guts', 'gtouchable', 'ghit']
+
+example_event_source = files('examples/event_example.cc')
+example_frame_source = files('examples/gframe_example.cc')
+example_run_source = files('examples/run_example.cc')
+
+verbosities = ['-verbosity.gevent_data=2',
+               '-debug.gevent_data=true',
+               '-verbosity.event_header=2',
+               '-debug.event_header=true',
+               '-verbosity.true_data=2',
+               '-debug.true_data=true',
+               '-verbosity.digitized_data=2',
+               '-debug.digitized_data=true',
+               '-verbosity.gtouchable=2',
+               '-debug.gtouchable=true'
+]
+
+verbosities_run = ['-verbosity.grun_data=2',
+                   '-debug.grun_data=true',
+]
+
+
+LD += {
+    'name' : sub_dir_name,
+    'sources' : files(
+        'gDigitizedData.cc',
+        'gTrueInfoData.cc',
+        'run/gRunDataCollection.cc',
+        'event/gEventDataCollection.cc'
+    ),
+    'headers' : files(
+        'gdataConventions.h',
+        'gDigitizedData.h',
+        'gDataCollection.h',
+        'gTrueInfoData.h',
+        'run/gRunHeader.h',
+        'run/gRunDataCollection.h',
+        'event/gEventHeader.h',
+        'event/gEventDataCollection.h',
+        'frame/gIntegralPayload.h',
+        'frame/gFrameHeader.h',
+        'frame/gFrameDataCollection.h'
+    ),
+    'additional_includes' : ['gdata', 'gdata/event', 'gdata/run'],
+
+    'dependencies' : [yaml_cpp_dep, clhep_deps, geant4_core_deps],
+    'internal_dependencies' : internal_deps,
+
+    'examples' : {
+        'test_gdata_event' : [example_event_source, ''],
+        'test_gdata_event_verbose' : [example_event_source, verbosities],
+        'test_gdata_gframe' : [example_frame_source, ''],
+        'test_gdata_gframe_verbose' : [example_frame_source, verbosities],
+        'test_gdata_run_event' : [example_run_source, ''],
+        'test_gdata_run_verbose' : [example_run_source, verbosities + verbosities_run] }
+}