Add AST-based public API checker and fix documentation gaps it found

.github/workflows/check_api_docs.yml

@@ -0,0 +1,81 @@
+name: "Check API documentation"
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check_api_docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Harden Runner
+        uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0
+        with:
+          egress-policy: audit
+
+      - name: Checkout pull request
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Install clang
+        # Used only as a subprocess for `clang++ -E -v` system-include-path discovery in
+        # extract_api.py; it does not need to version-match the pinned libclang pip wheel
+        # below, which does the actual AST parsing. Do not "fix" this to be version-matched.
+        run: sudo apt-get update && sudo apt-get install -y clang
+
+      - name: Install Python dependencies
+        run: pip install -r tools/api_checker/requirements.txt
+
+      - name: Extract API and regenerate the committed surface file
+        run: |
+          python3 tools/api_checker/extract_api.py \
+            --header include/nlohmann/json.hpp \
+            --include include \
+            --output /tmp/api_snapshot.json \
+            --surface-output tools/api_checker/api_surface.json
+
+      - name: "Check API documentation (Phase 1: advisory)"
+        # Surfaces missing/broken @sa links without failing the job while the backlog from the
+        # initial AST-based rollout is burned down. See tools/api_checker/POLICY.md and the PR
+        # that introduced this workflow for the two-phase rollout plan.
+        continue-on-error: true
+        run: |
+          python3 tools/api_checker/check_docs.py \
+            --snapshot /tmp/api_snapshot.json
+
+      - name: Check macro documentation (advisory only)
+        # Cross-checks docs/mkdocs/docs/api/macros/ pages against #define sites. Only checks the
+        # documented-macro-still-exists direction; never blocks CI. See POLICY.md.
+        run: python3 tools/api_checker/check_macros.py
+
+      - name: Check for uncommitted API surface changes
+        id: diff
+        run: |
+          mkdir -p ${{ github.workspace }}/patch
+          git diff --patch --no-color -- tools/api_checker/api_surface.json > ${{ github.workspace }}/patch/api_surface.patch
+          if [ -s ${{ github.workspace }}/patch/api_surface.patch ]; then
+            echo "tools/api_checker/api_surface.json is out of date. Diff:"
+            cat ${{ github.workspace }}/patch/api_surface.patch
+            echo "has_diff=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_diff=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # Uploaded so contributors can fix their PR with `git apply api_surface.patch`
+      # instead of installing libclang locally.
+      - name: Upload patch
+        if: steps.diff.outputs.has_diff == 'true'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: api-surface-patch
+          path: patch/api_surface.patch
+
+      - name: Fail if API surface file is not up to date
+        # Unlike the doc-backlog check above, this is purely mechanical regeneration with no
+        # backlog to phase in -- blocking from the start, matching check_amalgamation.yml's
+        # precedent. Contributors who add/remove/rename public API must regenerate and commit
+        # tools/api_checker/api_surface.json as part of their PR.
+        if: steps.diff.outputs.has_diff == 'true'
+        run: exit 1

.gitignore

@@ -3,6 +3,7 @@
 *.gcno
 *.gcda
 .DS_Store
+__pycache__/
 
 /.idea
 /cmake-build-*
@@ -43,5 +44,9 @@ venv
 
 nlohmann_json.spdx
 
+# api_checker: ephemeral, location/doc-status-sensitive working file (not the committed
+# release-tracking artifact -- see tools/api_checker/api_surface.json for that)
+/tools/api_checker/api_snapshot.json
+
 # Bazel-related
 MODULE.bazel.lock

README.md

@@ -106,7 +106,7 @@ Thanks everyone!
 
 :books: If you want to **learn more** about how to use the library, check out the rest of the [**README**](#examples), have a look at [**code examples**](https://github.com/nlohmann/json/tree/develop/docs/mkdocs/docs/examples), or browse through the [**help pages**](https://json.nlohmann.me).
 
-:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below.
+:construction: If you want to understand the **API** better, check out the [**API Reference**](https://json.nlohmann.me/api/basic_json/) or have a look at the [quick reference](#quick-reference) below. The public API surface is derived mechanically and checked for documentation coverage by the tooling in [`tools/api_checker/`](tools/api_checker/), whose [POLICY.md](tools/api_checker/POLICY.md) defines what counts as public API and what stability is guaranteed.
 
 :bug: If you found a **bug**, please check the [**FAQ**](https://json.nlohmann.me/home/faq/) if it is a known issue or the result of a design decision. Please also have a look at the [**issue list**](https://github.com/nlohmann/json/issues) before you [**create a new issue**](https://github.com/nlohmann/json/issues/new/choose). Please provide as much information as possible to help us understand and reproduce your issue.
 

docs/mkdocs/docs/api/basic_json/basic_json.md

@@ -420,7 +420,9 @@ basic_json(basic_json&& other) noexcept;
 1. Since version 1.0.0.
 2. Since version 1.0.0.
 3. Since version 2.1.0.
-4. Since version 3.2.0.
+4. Since version 3.2.0. Also initializes the position reported by
+   [`start_pos()`](start_pos.md)/[`end_pos()`](end_pos.md) from `val` when
+   [`JSON_DIAGNOSTIC_POSITIONS`](../macros/json_diagnostic_positions.md) is enabled, since version 3.12.0.
 5. Since version 1.0.0.
 6. Since version 1.0.0.
 7. Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/bjdata_version_t.md

@@ -0,0 +1,38 @@
+# <small>nlohmann::basic_json::</small>bjdata_version_t
+
+```cpp
+enum class bjdata_version_t
+{
+    draft2,
+    draft3,
+};
+```
+
+This enumeration is used in the [`to_bjdata`](to_bjdata.md) function to choose which draft version of
+the BJData specification to encode ND-array extensions for:
+
+draft2
+:   encode using the BJData Draft 2 ND-array format
+
+draft3
+:   encode using the BJData Draft 3 ND-array format
+
+## Examples
+
+??? example
+
+    The example shows how `bjdata_version_t` selects the BJData draft used by `to_bjdata`.
+
+    ```cpp
+    --8<-- "examples/bjdata_version_t.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/bjdata_version_t.output"
+    ```
+
+## Version history
+
+- Added in version 3.12.0.

docs/mkdocs/docs/api/basic_json/initializer_list_t.md

@@ -0,0 +1,32 @@
+# <small>nlohmann::basic_json::</small>initializer_list_t
+
+```cpp
+using initializer_list_t = std::initializer_list<detail::json_ref<basic_json>>;
+```
+
+The type used for the initializer-list [constructor](basic_json.md) (overload 5) and for functions
+such as [`operator=`](operator=.md) that accept a braced-init-list of JSON values. Each element wraps a
+`basic_json` value or something convertible to one, deferring the decision of whether the list should be
+parsed as a JSON array or a JSON object to the constructor itself.
+
+See the [constructor](basic_json.md) documentation for how `initializer_list_t` values are interpreted.
+
+## Examples
+
+??? example
+
+    The example shows how an `initializer_list_t` is used to construct a JSON value.
+
+    ```cpp
+    --8<-- "examples/initializer_list_t.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/initializer_list_t.output"
+    ```
+
+## Version history
+
+- Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/json_sax_t.md

@@ -0,0 +1,31 @@
+# <small>nlohmann::basic_json::</small>json_sax_t
+
+```cpp
+using json_sax_t = json_sax<basic_json>;
+```
+
+The [`json_sax`](../json_sax/index.md) interface bound to this `basic_json` specialization, i.e. with
+`BasicJsonType` fixed to `basic_json`. Used as the SAX interface type by [`sax_parse`](sax_parse.md) and
+other SAX-based parsing functions.
+
+See [`nlohmann::json_sax`](../json_sax/index.md) for more information.
+
+## Examples
+
+??? example
+
+    The example shows the type `json_sax_t`.
+
+    ```cpp
+    --8<-- "examples/json_sax_t.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/json_sax_t.output"
+    ```
+
+## Version history
+
+- Added in version 3.2.0.

docs/mkdocs/docs/api/basic_json/operator=.md

@@ -51,3 +51,5 @@ Linear.
 ## Version history
 
 - Added in version 1.0.0.
+- The `noexcept` specification was extended to also depend on
+  [`json_base_class_t`](json_base_class_t.md)'s move-assignment in version 3.11.3.

docs/mkdocs/docs/api/basic_json/operator_ValueType.md

@@ -85,3 +85,8 @@ Linear in the size of the JSON value.
 - Since version 1.0.0.
 - Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) added
   in version 3.9.0.
+- The exclusion of `std::any` from this conversion became conditional on
+  [`JSON_HAS_STATIC_RTTI`](../macros/json_has_static_rtti.md) in version 3.11.3.
+- `std::optional<T>` excluded from this conversion in version 3.13.0; use
+  [`get<std::optional<T>>()`](get.md)/[`get_to()`](get_to.md) instead (see
+  [Converting values](../../features/conversions.md)).

docs/mkdocs/docs/api/byte_container_with_subtype/container_type.md

@@ -0,0 +1,32 @@
+# <small>nlohmann::byte_container_with_subtype::</small>container_type
+
+```cpp
+using container_type = BinaryType;
+```
+
+The type of the underlying binary container, forwarded from the `BinaryType` template parameter that
+`byte_container_with_subtype` is instantiated with. `byte_container_with_subtype` publicly inherits from
+`container_type`.
+
+See [`basic_json::binary_t`](../basic_json/binary_t.md) for the type typically used to instantiate
+`BinaryType`.
+
+## Examples
+
+??? example
+
+    The example shows the type `container_type`.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__container_type.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/byte_container_with_subtype__container_type.output"
+    ```
+
+## Version history
+
+- Since version 3.8.0.

docs/mkdocs/docs/api/byte_container_with_subtype/operator_eq.md

@@ -0,0 +1,45 @@
+# <small>nlohmann::byte_container_with_subtype::</small>operator==
+
+```cpp
+bool operator==(const byte_container_with_subtype& rhs) const;
+```
+
+Compares two `byte_container_with_subtype` values for equality by comparing the underlying binary
+container, the subtype, and whether a subtype is set.
+
+## Parameters
+
+`rhs` (in)
+:   value to compare `*this` against
+
+## Return value
+
+whether `*this` and `rhs` are equal
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Linear in the size of the underlying binary container.
+
+## Examples
+
+??? example
+
+    The example demonstrates comparing `byte_container_with_subtype` values.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__operator_eq.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/byte_container_with_subtype__operator_eq.output"
+    ```
+
+## Version history
+
+- Since version 3.8.0.

docs/mkdocs/docs/api/byte_container_with_subtype/operator_ne.md

@@ -0,0 +1,45 @@
+# <small>nlohmann::byte_container_with_subtype::</small>operator!=
+
+```cpp
+bool operator!=(const byte_container_with_subtype& rhs) const;
+```
+
+Compares two `byte_container_with_subtype` values for inequality. Implemented as the negation of
+[`operator==`](operator_eq.md).
+
+## Parameters
+
+`rhs` (in)
+:   value to compare `*this` against
+
+## Return value
+
+whether `*this` and `rhs` are not equal
+
+## Exception safety
+
+No-throw guarantee: this function never throws exceptions.
+
+## Complexity
+
+Linear in the size of the underlying binary container.
+
+## Examples
+
+??? example
+
+    The example demonstrates comparing `byte_container_with_subtype` values.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__operator_ne.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/byte_container_with_subtype__operator_ne.output"
+    ```
+
+## Version history
+
+- Since version 3.8.0.

docs/mkdocs/docs/api/byte_container_with_subtype/subtype_type.md

@@ -0,0 +1,28 @@
+# <small>nlohmann::byte_container_with_subtype::</small>subtype_type
+
+```cpp
+using subtype_type = std::uint64_t;
+```
+
+The type used to store the optional binary subtype tag. See [`subtype`](subtype.md) and
+[`set_subtype`](set_subtype.md).
+
+## Examples
+
+??? example
+
+    The example shows the type `subtype_type`.
+
+    ```cpp
+    --8<-- "examples/byte_container_with_subtype__subtype_type.cpp"
+    ```
+
+    Output:
+
+    ```
+    --8<-- "examples/byte_container_with_subtype__subtype_type.output"
+    ```
+
+## Version history
+
+- Since version 3.8.0.