📝 add more examples

docs/examples/nlohmann_json_version.cpp

@@ -0,0 +1,12 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << "JSON for Modern C++ version "
+              << NLOHMANN_JSON_VERSION_MAJOR << "."
+              << NLOHMANN_JSON_VERSION_MINOR << "."
+              << NLOHMANN_JSON_VERSION_PATCH << std::endl;
+}

docs/examples/nlohmann_json_version.output

@@ -0,0 +1 @@
+JSON for Modern C++ version 3.10.5

docs/examples/ordered_json.cpp

@@ -0,0 +1,14 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using ordered_json = nlohmann::ordered_json;
+
+int main()
+{
+    ordered_json j;
+    j["one"] = 1;
+    j["two"] = 2;
+    j["three"] = 3;
+
+    std::cout << j.dump(2) << '\n';
+}

docs/examples/ordered_json.output

@@ -0,0 +1,5 @@
+{
+  "one": 1,
+  "two": 2,
+  "three": 3
+}

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

@@ -1,6 +1,5 @@
 # <small>nlohmann::basic_json::</small>object_comparator_t
 
-
 ```cpp
 using object_comparator_t = typename object_t::key_compare;
 // or

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

@@ -56,7 +56,6 @@ Linear in the size of the JSON value.
     [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) to `0` and replace any implicit
     conversions with calls to [`get`](../basic_json/get.md).
 
-
 ## Examples
 
 ??? example

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

@@ -44,13 +44,13 @@ Linear.
 
 ## Notes
 
-!!! note
+!!! note "Comparing special values"
 
     - NaN values never compare equal to themselves or to other NaN values.
     - JSON `#!cpp null` values are all equal.
     - Discarded values never compare equal to themselves.
 
-!!! note
+!!! note "Comparing floating-point numbers"
 
     Floating-point numbers inside JSON values numbers are compared with `json::number_float_t::operator==` which is
     `double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative

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

@@ -29,6 +29,22 @@ distinguishes these three types for numbers: [`number_unsigned_t`](number_unsign
 [`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used
 for floating-point numbers or to approximate integers which do not fit in the limits of their respective type.
 
+## Examples
+
+??? example
+
+    The following code how `type()` queries the `value_t` for all JSON types.
+    
+    ```cpp
+    --8<-- "examples/type.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/type.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

docs/mkdocs/docs/api/json.md

@@ -7,6 +7,22 @@ using json = basic_json<>;
 This type is the default specialization of the [basic_json](basic_json/index.md) class which uses the standard template
 types.
 
+## Examples
+
+??? example
+
+    The example below demonstrates how to use the type `nlohmann::json`.
+
+    ```cpp
+    --8<-- "examples/README.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/README.output"
+    ```
+
 ## Version history
 
 Since version 1.0.0.

docs/mkdocs/docs/api/json_pointer/index.md

@@ -14,11 +14,11 @@ are the base for JSON patches.
 `RefStringType`
 :   the string type used for the reference tokens making up the JSON pointer
 
-## Notes
+!!! warning "Deprecation"
 
-For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md) in
+    For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md)
-which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is deprecated
+    in which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is
-and may be removed in a future major version.
+    deprecated and may be removed in a future major version.
 
 ## Member types
 

docs/mkdocs/docs/api/macros/json_has_cpp_11.md

@@ -23,6 +23,19 @@ The default value is detected based on preprocessor macros such as `#!cpp __cplu
 - `#!cpp JSON_HAS_CPP_11` is always defined.
 - All macros are undefined outside the library.
 
+## Examples
+
+??? example
+
+    The code below forces the library to use the C++14 standard:
+
+    ```cpp
+    #define JSON_HAS_CPP_14 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history
 
 - Added in version 3.10.5.

docs/mkdocs/docs/api/macros/json_has_filesystem.md

@@ -25,6 +25,19 @@ The default value is detected based on the preprocessor macros `#!cpp __cpp_lib_
   filesystem support.
 - Both macros are undefined outside the library.
 
+## Examples
+
+??? example
+
+    The code below forces the library to use the header `<experimental/filesystem>`.
+
+    ```cpp
+    #define JSON_HAS_EXPERIMENTAL_FILESYSTEM 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history
 
 - Added in version 3.10.5.

docs/mkdocs/docs/api/macros/json_no_io.md

@@ -16,6 +16,20 @@ By default, `#!cpp JSON_NO_IO` is not defined.
 #undef JSON_NO_IO
 ```
 
+## Examples
+
+??? example
+
+    The code below forces the library not to use the headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and
+    `<ostream>`.
+
+    ```cpp
+    #define JSON_NO_IO 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history
 
 - Added in version 3.10.0.

docs/mkdocs/docs/api/macros/json_noexception.md

@@ -23,6 +23,19 @@ By default, the macro is not defined.
 The explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
 available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
 
+## Examples
+
+??? example
+
+    The code below switches off exceptions in the library.
+
+    ```cpp
+    #define JSON_NOEXCEPTION 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## See also
 
 - [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions

docs/mkdocs/docs/api/macros/json_skip_unsupported_compiler_check.md

@@ -15,6 +15,19 @@ By default, the macro is not defined.
 #undef JSON_SKIP_UNSUPPORTED_COMPILER_CHECK
 ```
 
+## Examples
+
+??? example
+
+    The code below switches off the check whether the compiler is supported.
+
+    ```cpp
+    #define JSON_SKIP_UNSUPPORTED_COMPILER_CHECK 1
+    #include <nlohmann/json.hpp>
+
+    ...
+    ```
+
 ## Version history
 
 Added in version 3.2.0.

docs/mkdocs/docs/api/macros/nlohmann_json_version_major.md

@@ -13,6 +13,23 @@ These macros are defined by the library and contain the version numbers accordin
 
 The macros are defined according to the current library version.
 
+## Examples
+
+??? example
+
+    The example below shows how `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, and
+    `NLOHMANN_JSON_VERSION_PATCH` are defined by the library.
+
+    ```cpp
+    --8<-- "examples/nlohmann_json_version.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_version.output"
+    ```
+
 ## See also
 
 - [meta](../basic_json/meta.md) - returns version information on the library

docs/mkdocs/docs/api/ordered_json.md

@@ -6,9 +6,26 @@ using ordered_json = basic_json<ordered_map>;
 
 This type preserves the insertion order of object keys.
 
+## Examples
+
+??? example
+
+    The example below demonstrates how `ordered_json` preserves the insertion order of object keys.
+
+    ```cpp
+    --8<-- "examples/ordered_json.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/ordered_json.output"
+    ```
+
 ## See also
 
 - [ordered_map](ordered_map.md)
+- [Object Order](../features/object_order.md)
 
 ## Version history
 

docs/mkdocs/docs/features/object_order.md

@@ -42,30 +42,13 @@ If you do want to preserve the **insertion order**, you can try the type [`nlohm
 ??? example
 
     ```cpp
-    #include <iostream>
+    --8<-- "examples/ordered_json.cpp"
-    #include <nlohmann/json.hpp>
-    
-    using ordered_json = nlohmann::ordered_json;
-    
-    int main()
-    {
-        ordered_json j;
-        j["one"] = 1;
-        j["two"] = 2;
-        j["three"] = 3;
-        
-        std::cout << j.dump(2) << '\n';
-    }
     ```
     
     Output:
     
     ```json
-    {
+    --8<-- "examples/ordered_json.output"
-      "one": 1,
-      "two": 2,
-      "three": 3
-    }
     ```
 
 Alternatively, you can use a more sophisticated ordered map like [`tsl::ordered_map`](https://github.com/Tessil/ordered-map) ([integration](https://github.com/nlohmann/json/issues/546#issuecomment-304447518)) or [`nlohmann::fifo_map`](https://github.com/nlohmann/fifo_map) ([integration](https://github.com/nlohmann/json/issues/485#issuecomment-333652309)).