Add documentation for comparing json and ordered_json

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;
+}

docs/examples/operator__equal__specializations.output

@@ -0,0 +1,2 @@
+true
+false

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 results. For instance, comparing the JSON
+    objects
+
+    ```json
+    {
+       "version": 1,
+       "type": "integer"
+    }
+    ```
+
+    and
+
+    ```json
+    {
+       "type": "integer",
+       "version": 1
+    }
+    ```
+
+    depends on whether [`nlohmann::json`](../json.md) order [`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