Menu

#656 GTK3V2MAIN: Doxygen main-page/dev-docs improvements, Phase A (project name, brief, logo, search, treeview)

nobody
None
2 days ago
2 days ago
No

First phase of a small effort to make the generated Doxygen internals docs (docs/doxygen/) actually usable, not just gate-passing. Full plan: git's .claude/doxygen-mainpage-plan.md (a working-notes file, not committed).

Config-only changes to docs/doxygen/Doxyfile.in, plus a new small logo asset:

  • PROJECT_NAME typo fixed: "XTrackCAD" -> "XTrkCAD" -- this was rendering on every single generated page's title bar.
  • PROJECT_BRIEF set to a short one-line tagline (was empty).
  • PROJECT_LOGO set to a new resized (195x55, within Doxygen's 200x55 limit) copy of app/wlib/gtk3lib/ui/bitmaps/logo.png, saved as docs/doxygen/logo.png. Was empty.
  • SEARCHENGINE changed NO -> YES: adds client-side search, previously entirely absent for a ~105K-line codebase.
  • GENERATE_TREEVIEW changed NO -> YES: adds sidebar navigation. Measured cost is small: output grew 70M -> 74M (+6%), 1013 -> 1453 files, build time ~1.2s -> ~1.66s.

Two items investigated for this same pass were dropped, not included here:

  • Removing two ALIASES (logcmd, prefs) that appeared unused -- turned out to have 19 real call sites; removing them broke the FAIL_ON_WARNINGS build. Left in place.
  • Enabling HAVE_DOT/CALL_GRAPH/CALLER_GRAPH -- measured at 1.1G output (~15x growth) and 22.9s build time (~15x), and breaks FAIL_ON_WARNINGS outright: Doxygen's default DOT_GRAPH_MAX_NODES=50 is far too low for several of this codebase's most-shared utility functions (NormalizeAngle needs 199 nodes, FindDistance 178, CreateMenus 155). Raising the limit would produce some very large diagrams for the worst offenders rather than cleanly resolving the tension. Posted to the development mailing list for discussion rather than deciding unilaterally; tracked as a separate follow-up, not part of this bug.

Verification: docs-doxygen exits 0 with FAIL_ON_WARNINGS active, using the CI-pinned Doxygen 1.15.0 binary. Full rebuild clean, ctest 10/10 pass. Git PR: https://github.com/adbyrne/XTrkCAD/pull/25 (GTK3V2MAIN).

Discussion

Anonymous
Anonymous

Add attachments
Cancel