Merge branch 'develop' into claude/todo-191-plan-508110

Resolve the conflict in docs/mkdocs/docs/home/architecture.md by taking
develop's rewritten page and pointing its ordered_map links at the moved
api/ordered_map/index.md. Also update the ordered_map.md links develop
added in ordered_json.md, object_order.md, and template_parameters.md.

Regenerate api_surface.json for the new BON8 functions and the changed
comparison operator. Restrict the documented_non_public leak check to
@sa URLs into json.nlohmann.me: develop now uses @sa to link GitHub
issues from private members such as copy_structured, which is not a
documentation leak.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

tools/api_checker/README.md

@@ -126,8 +126,9 @@ includes via `clang++ -E -x c++ -v /dev/null`, and walks the AST:
 ```
 
 `documented_non_public` lists entities **not** part of the public surface (private/protected members of
-the six tracked classes) that surprisingly carry a real `@sa` URL — a genuine documentation leak. It does
-not list public entries that merely lack `@sa`; that's `check_docs.py`'s job.
+the six tracked classes) that surprisingly carry an `@sa` URL into the documentation site
+(`https://json.nlohmann.me/`) — a genuine documentation leak. `@sa` links to anything else, such as GitHub
+issues, are ignored. It does not list public entries that merely lack `@sa`; that's `check_docs.py`'s job.
 
 **Output (surface, from `--surface-output`):**
 ```json

tools/api_checker/api_surface.json

@@ -46,7 +46,7 @@
       "name": "operator<",
       "pretty_signature": "nlohmann::operator<",
       "scope": "nlohmann",
-      "signature": "friend bool operator<(const_reference lhs, const_reference rhs) noexcept { JSON_IMPLEMENT_OPERATOR( <, false, false, operator<(lhs_type, rhs_type)) }",
+      "signature": "friend bool operator<(const_reference lhs, const_reference rhs) noexcept { JSON_IMPLEMENT_OPERATOR( <, false, false, operator<(lhs_type, rhs_type), compare_iteratively<true>(lhs, rhs, true) == compare_result::less, false) }",
       "tier": "callable"
     },
     {
@@ -850,6 +850,24 @@
       "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bjdata(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true)",
       "tier": "callable"
     },
+    {
+      "identity_name": "from_bon8",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "from_bon8",
+      "pretty_signature": "nlohmann::basic_json::from_bon8",
+      "scope": "nlohmann::basic_json",
+      "signature": "template<typename InputType> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bon8(InputType&& i, const bool strict = true, const bool allow_exceptions = true)",
+      "tier": "callable"
+    },
+    {
+      "identity_name": "from_bon8",
+      "kind": "FUNCTION_TEMPLATE",
+      "name": "from_bon8",
+      "pretty_signature": "nlohmann::basic_json::from_bon8",
+      "scope": "nlohmann::basic_json",
+      "signature": "template<typename IteratorType, typename SentinelType = IteratorType, detail::enable_if_t<detail::can_compare_ne<IteratorType, SentinelType>::value, int> = 0> JSON_HEDLEY_WARN_UNUSED_RESULT static basic_json from_bon8(IteratorType first, SentinelType last, const bool strict = true, const bool allow_exceptions = true)",
+      "tier": "callable"
+    },
     {
       "identity_name": "from_bson",
       "kind": "CXX_METHOD",
@@ -1966,6 +1984,33 @@
       "signature": "static void to_bjdata(const basic_json& j, detail::output_adapter<std::uint8_t> o, const bool use_size = false, const bool use_type = false, const bjdata_version_t version = bjdata_version_t::draft2)",
       "tier": "callable"
     },
+    {
+      "identity_name": "to_bon8",
+      "kind": "CXX_METHOD",
+      "name": "to_bon8",
+      "pretty_signature": "nlohmann::basic_json::to_bon8",
+      "scope": "nlohmann::basic_json",
+      "signature": "static std::vector<std::uint8_t> to_bon8(const basic_json& j)",
+      "tier": "callable"
+    },
+    {
+      "identity_name": "to_bon8",
+      "kind": "CXX_METHOD",
+      "name": "to_bon8",
+      "pretty_signature": "nlohmann::basic_json::to_bon8",
+      "scope": "nlohmann::basic_json",
+      "signature": "static void to_bon8(const basic_json& j, detail::output_adapter<char> o)",
+      "tier": "callable"
+    },
+    {
+      "identity_name": "to_bon8",
+      "kind": "CXX_METHOD",
+      "name": "to_bon8",
+      "pretty_signature": "nlohmann::basic_json::to_bon8",
+      "scope": "nlohmann::basic_json",
+      "signature": "static void to_bon8(const basic_json& j, detail::output_adapter<std::uint8_t> o)",
+      "tier": "callable"
+    },
     {
       "identity_name": "to_bson",
       "kind": "CXX_METHOD",
@@ -2383,8 +2428,8 @@
     {
       "identity_name": "operator string_t",
       "kind": "CONVERSION_FUNCTION",
-      "name": "operator typename string_t_helper<type-parameter-0-0>::type",
-      "pretty_signature": "nlohmann::json_pointer::operator typename string_t_helper<type-parameter-0-0>::type",
+      "name": "operator nlohmann::json_pointer::string_t_helper<type-parameter-0-0>::type",
+      "pretty_signature": "nlohmann::json_pointer::operator nlohmann::json_pointer::string_t_helper<type-parameter-0-0>::type",
       "scope": "nlohmann::json_pointer",
       "signature": "JSON_HEDLEY_DEPRECATED_FOR(3.11.0, to_string()) operator string_t() const",
       "tier": "callable"

tools/api_checker/extract_api.py

@@ -35,6 +35,10 @@ except ImportError:
 
 ABI_TAG_PATTERN = re.compile(r'::json(?:_abi)?[a-z_]*_v\d+_\d+_\d+(?=::|$)')
 
+# Only @sa URLs into the documentation site are doc links; internal code also uses @sa to point at
+# GitHub issues (e.g. the recursion-limit rationale), which is not a documentation leak.
+DOCS_SITE_URL = 'https://json.nlohmann.me/'
+
 # Bump whenever a change to this schema, or to the identity-computing algorithm
 # (get_signature_text()/get_identity_name()/identity_key()), could alter the 'signature' or
 # 'identity_name' text for otherwise-unchanged source. diff_api.py refuses by default to compare
@@ -377,7 +381,7 @@ def walk_class_template(cursor, public_classes: set, api_dict: dict, documented_
             # nonetheless carry a real @sa URL -- a genuine documentation leak, not "any
             # public member missing @sa" (that's what check_docs.py's missing-@sa check is for).
             leaked_url = extract_sa_url(child.raw_comment)
-            if leaked_url:
+            if leaked_url and leaked_url.startswith(DOCS_SITE_URL):
                 documented_non_public.append({
                     'location': cursor_location(child),
                     'raw_comment_excerpt': (child.raw_comment or '')[:100],