From c864df33415dd0ea89cd6abd6e0f966215648d72 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Sat, 5 Sep 2026 10:05:54 +0200
Subject: [PATCH] Spell out the move rationale at every handle_value(std::move)
 site

The comment explaining why the value is moved sat only on
json_sax_dom_parser::string(), and the callback parser's string() pointed
at it with "see json_sax_dom_parser::string()". That reference cannot be
searched for - the function is declared as `bool string(string_t& val)`
inside the class, so the qualified name appears nowhere - and the two
binary() overloads, which have always moved, carried no explanation at all.

Put the same comment on all four sites and name json_sax, which is
greppable, instead of a member that is not.

Comment-only; no generated code changes.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
---
 include/nlohmann/detail/input/json_sax.hpp | 11 ++++++++---
 single_include/nlohmann/json.hpp           | 11 ++++++++---
 2 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/include/nlohmann/detail/input/json_sax.hpp b/include/nlohmann/detail/input/json_sax.hpp
index daad030ab..1627d2326 100644
--- a/include/nlohmann/detail/input/json_sax.hpp
+++ b/include/nlohmann/detail/input/json_sax.hpp
@@ -222,14 +222,16 @@ class json_sax_dom_parser
 
     bool string(string_t& val)
     {
-        // the interface allows moving the value (see json_sax::string), which
-        // hands the lexer's buffer to the new value instead of copying it
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }
 
     bool binary(binary_t& val)
     {
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }
@@ -534,13 +536,16 @@ class json_sax_dom_callback_parser
 
     bool string(string_t& val)
     {
-        // see json_sax_dom_parser::string()
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }
 
     bool binary(binary_t& val)
     {
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }
diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp
index a65dd226a..4fa86f0a8 100644
--- a/single_include/nlohmann/json.hpp
+++ b/single_include/nlohmann/json.hpp
@@ -10804,14 +10804,16 @@ class json_sax_dom_parser
 
     bool string(string_t& val)
     {
-        // the interface allows moving the value (see json_sax::string), which
-        // hands the lexer's buffer to the new value instead of copying it
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }
 
     bool binary(binary_t& val)
     {
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }
@@ -11116,13 +11118,16 @@ class json_sax_dom_callback_parser
 
     bool string(string_t& val)
     {
-        // see json_sax_dom_parser::string()
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }
 
     bool binary(binary_t& val)
     {
+        // json_sax documents that the passed value may be moved from,
+        // so hand the buffer over instead of copying it
         handle_value(std::move(val));
         return true;
     }