docs, integrate workspace reports + complete Doxygen alias system into one DRY Doxygen reference

[steven-varga]

Summary

Two interlocking goals, one issue:

1. Integrate the durable workspace reports (vargalabs-workspace/tasks/h5cpp-*.md) into docs/reports/ and wire them into the Doxygen API reference as a real navigation tree (@page / @subpage). Each report carries hand-authored cross-references to relevant examples/*/ directories.
2. Resurrect and complete the Doxygen alias system (docs/links/*.txt) so docstrings across the codebase use a DRY controlled vocabulary instead of inline duplication. Vocabulary specification lives in vargalabs-workspace/tasks/h5cpp-doxygen-alias-vocabulary.md and ships as docs/aliases.md for the public API site.

Together they make the published docs site serve the same role inside the codebase (developer reference for writing docs) and outside it (reader's map across API + prose + runnable code). One source of truth — docs/links/*.txt for vocabulary, docs/reports/ for prose, examples/ for runnable code — all rendered into one navigable Doxygen sidebar.

Goal — single navigable surface

docs.h5cpp.org/api/
├── Modules ………………………… (auto)
├── Classes …………………………… (auto)
├── Files …………………………… (auto)
├── Examples ………………………… (auto, from EXAMPLE_PATH)
└── Reports ………………………… (new)
    ├── Architecture                       (12 reports)
    ├── Inventories & guides               (4 reports + aliases.md)
    ├── Taxonomies — compiler backends     (9 reports)
    ├── Surveys & comparisons              (5 reports)
    ├── Compatibility & quality            (4 reports)
    └── Project context                    (3 reports)

Part A — Doxygen alias system (do first)

Done first because every report's "Related examples" section and every coverage-push docstring should use the canonical aliases from day one. Spec at tasks/h5cpp-doxygen-alias-vocabulary.md.

A.1 Dedup & deprecate (one commit)

• Drop returns_void (identical content to returns_err; the latter has 6 callers, the former 0).
• Audit the 5 zero-caller \func_* aliases (func_create_hdr, func_create_links, func_write_hdr, func_write_desc, func_read_desc): either adopt across the relevant H5F/H5D create/write headers in the same commit, or remove.
• Decide on tpar_obj vs tpar_T overlap (fold into one).

A.2 Add v1.12.6 surface aliases (one commit)

Add the proposed aliases from tasks/h5cpp-doxygen-alias-vocabulary.md §5:

• Parameters: par_attr, par_mdspan, par_sparse, par_ref_t, par_handle, par_thread_count
• Returns: returns_gr, returns_ref, returns_paths
• See-also: sa_sparse, sa_mdspan, sa_async, sa_token
• Function-group headers: func_attr_hdr, func_sparse_hdr, func_async_hdr, func_traversal_hdr

A.3 Mandate aliases-first (one commit + repo docs)

• Add a top-of-file note in each docs/links/*.txt pointing at docs/aliases.md as the canonical developer reference.
• Add a short section to CONTRIBUTING.md (create if missing) describing the alias-first rule for new docstrings: "If a @param / @tparam / @return line repeats ≥ 5× across the codebase, add it to docs/links/h5cpp.txt and reference it via \name."
• Add docs/aliases.md (the publishable companion to the workspace vocabulary report). Goes under Inventories & guides in the Reports tree.

A.4 Ratchet (one commit, optional)

• Modify .github/workflows/docs.yml to upload WARN_LOGFILE as an artifact so undocumented-entity counts are visible per run. Pre-step toward WARN_AS_ERROR=YES when coverage reaches a sensible threshold.

Part B — Reports integration (build on Part A)

B.1 Curated include list — redline this

The 50 workspace reports split into 37 durable + 13 ephemeral. Strike anything you'd rather drop; add anything I've excluded.

✔ Include (37)

Architecture & design (12)

• h5cpp-type-system-architecture-notes.md
• h5cpp-type-system-map.md
• h5cpp-async-mode-compile-time-thread-safety-design.md
• h5cpp-threaded-pipeline-sigma-queue-design.md
• h5cpp-fapl-multithreading-workplan.md
• h5cpp-compiler-scatter-gather-design.md
• h5cpp-compiler-scatter-gather-visitor-refactor.md
• h5cpp-compiler-multi-backend-architecture.md
• h5cpp-reflection-cpp26-roadmap.md
• h5cpp-performance-evaluation-framework-design.md
• h5cpp-performance-comparison-framework.md
• h5cpp-phase-1.3-pt-t-pool-integration-notes.md (phase-specific — drop if obsolete)

Inventories & guides (4 + aliases.md added by Part A.3)

• h5cpp-handle-inventory.md → examples/cout/, examples/reference/
• h5cpp-filters-inventory-and-use-guide.md → examples/custom-pipeline/, examples/datasets/
• h5cpp-stl-pretty-print-guide.md → examples/cout/, examples/stl/, examples/pprint/
• h5cpp-hdf5-112-feature-report.md → examples/reference/, examples/mdspan/
• docs/aliases.md (new, ships from Part A.3)

Attribute taxonomies — compiler backends (9)

• h5cpp-compiler-h5-attribute-taxonomy.md → examples/attributes/
• h5cpp-compiler-avro-attribute-taxonomy.md
• h5cpp-compiler-bson-attribute-taxonomy.md
• h5cpp-compiler-cbor-attribute-taxonomy.md
• h5cpp-compiler-json-attribute-taxonomy.md
• h5cpp-compiler-msgpack-attribute-taxonomy.md
• h5cpp-compiler-pb-attribute-taxonomy.md
• h5cpp-compiler-rlp-attribute-taxonomy.md
• h5cpp-compiler-sql-attribute-taxonomy.md

Surveys & comparisons (5)

• h5cpp-compiler-hdf5-vs-protobuf-comparison.md
• h5cpp-vs-h5py-syntax.md → examples/basics/, examples/datasets/
• h5cpp-compiler-prior-art-survey.md
• h5cpp-compiler-backend-cookbook.md → examples/multi-tu/, examples/compound/
• h5cpp-compiler-next-backends-difficulty-ranking.md

Compatibility & quality (4)

• h5cpp-compatibility-mechanisms-report.md → examples/reference/, examples/attributes/
• h5cpp-study-hdf5-bugs-top10.md
• h5cpp-doxygen-alias-support-report.md
• h5cpp-study-struct-falsification.md

Project context (3)

• h5cpp-product-positioning.md
• h5cpp-study-positioning-v2.md (supersedes -positioning)
• h5cpp-usability-evaluation.md

✘ Exclude (13)

Ephemeral / superseded / stale-by-design — would clutter the sidebar without durable value:

• h5cpp-branch-mining-report.md (one-off branch survey)
• h5cpp-call-the-doctor-guide-brainstorm.md (brainstorm)
• h5cpp-ci-pattern-study.md (internal CI lesson; meta)
• h5cpp-compile-warnings-report.md (tactical)
• h5cpp-compiler-last-release-notes.md (obsolete)
• h5cpp-compiler-backends-1-6-workplan.md (WIP plan)
• h5cpp-examples-coverage-assessment.md (superseded by v1.12.6 examples sweep)
• h5cpp-issue-roadmap.md (live roadmap, naturally stale)
• h5cpp-pipeline-performance-analysis-report.md (one-off run)
• h5cpp-staging-release-diff-report.md (ephemeral)
• h5cpp-study-positioning.md (superseded by v2)
• h5cpp-study-preliminary-report.md (superseded by final)
• h5cpp-study-final-report.md (extract durable parts elsewhere)

B.2 Implementation

One commit per category to keep PR review manageable:

1. docs/reports/architecture/ + index page + @page directives + example cross-refs.
2. docs/reports/inventories/ + index page + docs/aliases.md from Part A + cross-refs.
3. docs/reports/taxonomies/ (the 9 compiler taxonomies).
4. docs/reports/surveys/, docs/reports/compatibility/, docs/reports/project/.
5. docs/reports/index.md master page + doxy/Doxyfile INPUT += ../docs/reports extension.

Each report needs a two-line @page header inserted at the top:

<!--
@page reports_handle_inventory  Handle inventory
@subpage_of reports_inventories
-->

(Use literal HTML comments; Doxygen parses @page inside them. The @subpage_of is a project convention — actual Doxygen requires the parent page to declare @subpage child in its body.)

B.3 Example cross-references (hand-authored)

Each report's mapping to examples/*/ is in §B.1 above. Implementation: append a "Related examples" section at the end of each report:

## Related examples

- \ref examples/cout/cout.cpp "Handle pretty-printing"
- \ref examples/reference/reference.cpp "Reference handle lifecycle"

Reports without an obvious example map (most architecture docs, taxonomies) skip the section.

Out of scope (file separately)

• Bump Doxyfile PROJECT_NUMBER from stale 1.10.4.6 → @PROJECT_VERSION@ via Doxyfile.in + configure_file.
• Enable EXTRACT_ALL / JAVADOC_AUTOBRIEF to surface undocumented APIs.
• Fix the 49-of-62 headers with zero Doxygen markers. Separate, much larger coverage push — this issue creates the infrastructure (alias vocabulary + aliases.md reference) it'll consume.
• Move MkDocs and Doxygen deploys to keep_files: false for proper cleanup of removed pages.

Acceptance criteria

Part A — Aliases

• returns_void removed; callers (if any) migrated to returns_err
• Zero-caller \func_* aliases either adopted across H5F/H5D create/write headers or removed
• tpar_obj vs tpar_T overlap resolved (one alias remains)
• v1.12.6 surface aliases added (par_attr, par_mdspan, par_sparse, par_ref_t, par_handle, par_thread_count, returns_gr, returns_ref, returns_paths, sa_sparse, sa_mdspan, sa_async, sa_token, func_attr_hdr, func_sparse_hdr, func_async_hdr, func_traversal_hdr)
• docs/aliases.md exists with the publishable catalog and standard docstring template
• CONTRIBUTING.md carries the alias-first rule for new docstrings
• docs/links/*.txt files have a top-of-file comment pointing at docs/aliases.md
• (Optional) docs.yml uploads WARN_LOGFILE as an artifact

Part B — Reports

• Curated reports (final list post-redline) committed under docs/reports/<category>/
• One index file per category (docs/reports/<category>/index.md) with @page + @subpage chain
• docs/reports/index.md master page declares @subpage for each category index
• Each leaf report carries @page + (where applicable) "Related examples" section with \ref / \example links
• doxy/Doxyfile INPUT += ../docs/reports
• CI doc build renders the new tree without new warnings
• Local doxygen Doxyfile produces clean HTML with "Project Reports" sidebar entry visible

References

• Vocabulary spec: vargalabs-workspace/tasks/h5cpp-doxygen-alias-vocabulary.md (workspace source-of-thought; not committed to the repo)
• Current alias files: docs/links/{h5cpp,hdf5,linalg,stl}.txt
• Existing canonical usage example: h5cpp/H5Dread.hpp (18 alias uses)