mirror of
https://github.com/nlohmann/json.git
synced 2026-07-12 05:25:09 +00:00
Niels Lohmann
f23b3c63a2
Adds tools/api_checker/: extract_api.py derives the public API surface directly from the libclang AST (independent of documentation status), check_docs.py flags public entries missing @sa links (and @sa on non-public ones), diff_api.py does an overload-aware breaking/feature diff between two refs, check_macros.py cross- checks documented macros against #define sites, and snapshot_release.py backfills immutable per-release surface snapshots into tools/api_checker/history/ (v3.1.0 through v3.12.0) so diff_api.py can compare releases without live extraction. POLICY.md documents what counts as public API and what stability is guaranteed. Running this tooling against the current tree found and fixed a real documentation backlog: ~25 new API doc pages (ordered_map's methods, json_sax's ctor/dtor/ operator=, byte_container_with_subtype's comparison operators, several orphaned type aliases), each with a compiled and output-verified example, plus missing @sa comments and stale/incorrect Version History entries on several existing pages (found by diffing consecutive release pairs and checking whether the resulting change was actually reflected in the target page's history section). Also adds docs/home/api_changes.md, a per-release, per-function reference of public API changes (v3.1.0 through v3.12.0) generated from the history/ snapshots, complementing (not replacing) the existing release notes. Along the way, found and fixed several extractor bugs by testing against real release tags rather than trusting the algorithm in isolation -- most notably an identity-key scheme based on libclang's USR that encoded the enclosing class template's own arity, and a since-renamed ABI inline-namespace pattern (json_v3_11_0 vs. today's json_abi_v3_11_2) that neither of two earlier regex attempts stripped correctly. Both are documented in extract_api.py's docstrings and tools/api_checker/history/README.md so the failure mode doesn't recur silently. .github/workflows/check_api_docs.yml runs extract_api.py + check_docs.py in CI, advisory-only for now (documented backlog may not be at zero for entities this PR didn't touch), plus a blocking drift check on the committed tools/api_checker/api_surface.json. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Niels Lohmann <mail@nlohmann.me>
API surface history
One file per released v3.* tag: <tag>.json, e.g. v3.12.0.json. Each is the output of
extract_api.py --surface-output at that tag (see tools/api_checker/README.md for the schema),
with additional immutable provenance in meta: ref, commit (the tag's resolved commit sha),
generated_at, and generator.
Conventions
- Immutable once committed. Files here are never hand-edited or silently regenerated.
snapshot_release.pyrefuses to overwrite an existing file unless--forceis passed, and that should only happen for a deliberate, reviewed fix — the resulting diff should be inspected before committing, same as any other source change. - Generated by
tools/api_checker/snapshot_release.py, run manually as part of cutting a release (seetools/api_checker/README.md's "Workflow: Release Checklist"). Not CI-automated. diff_api.pyuses these automatically.--old/--newcheck here first (matching the ref string to<ref>.json) before falling back to livegit archiveextraction — seetools/api_checker/README.md'sdiff_api.pysection.
Coverage
Backfilled: every v3.* tag from v3.1.0 through the latest release at backfill time
(v3.12.0), covering the full public API history of the include/nlohmann/ header layout.
Format history
format_version: 2(current). Fixedextract_api.py'sABI_TAG_PATTERNto also strip the pre-rename ABI inline-namespace form used byv3.11.0/v3.11.1:json_v3_11_0(no_abisegment), renamed to today'sjson_abi_v3_11_2-style tag starting withv3.11.2. Underformat_version: 1, that older form wasn't recognized, so everyscope/signatureatv3.11.0/v3.11.1retained the raw un-stripped namespace segment, makingdiff_api.pyreport essentially the entire API (~330 of ~332 entries) as removed-and-readded acrossv3.10.5->v3.11.0->v3.11.1->v3.11.2— a bug of the same shape as the earlier USR-arity issue documented inextract_api.py'sidentity_key()docstring, caught the same way: by actually diffing real consecutive release pairs instead of trusting the extractor in isolation. All 27 files were regenerated underformat_version: 2; onlyv3.11.0.jsonandv3.11.1.jsonactually changed content (every other tag's scopes never contained the old-style tag).
Known gaps
v3.0.0,v3.0.1: not backfilled. These predate theinclude/nlohmann/directory structure entirely — headers lived undersrc/at that point (a singlesrc/json.hpp). Sinceextract_api.pyhardcodesinclude/nlohmann/json.hppas the entry point,snapshot_release.py --all-tagsfails cleanly on these two refs (git archive ... -- includefinds nothing) rather than silently producing a wrong/empty result. Not pursued: two tags, immediately superseded byv3.1.0, and supporting the pre-restructuring layout would need a separate header/include-path convention with no other benefit. If full pre-3.1 coverage is ever wanted,extract_api.pywould need asrc/json.hpp-aware mode first.- Pre-
v3.0.0tags (v1.x,v2.x,v3.0.0-rc*, etc.) were never attempted — out of scope for this backfill; seetools/api_checker/POLICY.mdfor the stated boundary.