From 2d48a4d9c5e8f0a5ce914922eb2a45dc0ec93ee3 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Sat, 23 Jul 2022 20:54:40 +0200
Subject: [PATCH] Add documentation for comparing json and ordered_json (#3599)

* :memo: add documentation for #3443

* Apply suggestions from code review

Co-authored-by: Florian Albrechtskirchinger <falbrechtskirchinger@gmail.com>
---
 .../operator__equal__specializations.cpp      | 16 +++++++++
 .../operator__equal__specializations.output   |  2 ++
 .../mkdocs/docs/api/basic_json/operator_eq.md | 33 +++++++++++++++++++
 3 files changed, 51 insertions(+)
 create mode 100644 docs/examples/operator__equal__specializations.cpp
 create mode 100644 docs/examples/operator__equal__specializations.output

diff --git a/docs/examples/operator__equal__specializations.cpp b/docs/examples/operator__equal__specializations.cpp
new file mode 100644
index 0000000000..97d5ecead3
--- /dev/null
+++ b/docs/examples/operator__equal__specializations.cpp
@@ -0,0 +1,16 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    nlohmann::json uj1 = {{"version", 1}, {"type", "integer"}};
+    nlohmann::json uj2 = {{"type", "integer"}, {"version", 1}};
+
+    nlohmann::ordered_json oj1 = {{"version", 1}, {"type", "integer"}};
+    nlohmann::ordered_json oj2 = {{"type", "integer"}, {"version", 1}};
+
+    std::cout << std::boolalpha << (uj1 == uj2) << '\n' << (oj1 == oj2) << std::endl;
+}
diff --git a/docs/examples/operator__equal__specializations.output b/docs/examples/operator__equal__specializations.output
new file mode 100644
index 0000000000..da29283aaa
--- /dev/null
+++ b/docs/examples/operator__equal__specializations.output
@@ -0,0 +1,2 @@
+true
+false
diff --git a/docs/mkdocs/docs/api/basic_json/operator_eq.md b/docs/mkdocs/docs/api/basic_json/operator_eq.md
index 6c86bf13e1..b4d61b6371 100644
--- a/docs/mkdocs/docs/api/basic_json/operator_eq.md
+++ b/docs/mkdocs/docs/api/basic_json/operator_eq.md
@@ -99,6 +99,39 @@ Linear.
     }
     ```
 
+!!! note "Comparing different `basic_json` specializations"
+
+    Comparing different `basic_json` specializations can have surprising effects. For instance, the result of comparing
+    the JSON objects
+
+    ```json
+    {
+       "version": 1,
+       "type": "integer"
+    }
+    ```
+
+    and
+
+    ```json
+    {
+       "type": "integer",
+       "version": 1
+    }
+    ```
+
+    depends on whether [`nlohmann::json`](../json.md) or [`nlohmann::ordered_json`](../ordered_json.md) is used:
+
+     ```cpp
+     --8<-- "examples/operator__equal__specializations.cpp"
+     ```
+     
+     Output:
+     
+     ```json
+     --8<-- "examples/operator__equal__specializations.output"
+     ```
+
 ## Examples
 
 ??? example