📝 add some examples

docs/examples/nlohmann_json_namespace.cpp

@@ -0,0 +1,14 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// possible use case: use NLOHMANN_JSON_NAMESPACE instead of nlohmann
+using json = NLOHMANN_JSON_NAMESPACE::json;
+
+// macro needed to output the NLOHMANN_JSON_NAMESPACE as string literal
+#define Q(x) #x
+#define QUOTE(x) Q(x)
+
+int main()
+{
+    std::cout << QUOTE(NLOHMANN_JSON_NAMESPACE) << std::endl;
+}

docs/examples/nlohmann_json_namespace.output

@@ -0,0 +1 @@
+nlohmann::json_v3_11_1

docs/examples/nlohmann_json_namespace_begin.c++17.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <optional>
+#include <nlohmann/json.hpp>
+
+// partial specialization (see https://json.nlohmann.me/features/arbitrary_types/)
+NLOHMANN_JSON_NAMESPACE_BEGIN
+template <typename T>
+struct adl_serializer<std::optional<T>>
+{
+    static void to_json(json& j, const std::optional<T>& opt)
+    {
+        if (opt == std::nullopt)
+        {
+            j = nullptr;
+        }
+        else
+        {
+            j = *opt;
+        }
+    }
+};
+NLOHMANN_JSON_NAMESPACE_END
+
+int main()
+{
+    std::optional<int> o1 = 1;
+    std::optional<int> o2 = std::nullopt;
+
+    NLOHMANN_JSON_NAMESPACE::json j;
+    j.push_back(o1);
+    j.push_back(o2);
+    std::cout << j << std::endl;
+}

docs/examples/nlohmann_json_namespace_begin.c++17.output

@@ -0,0 +1 @@
+[1,null]

docs/mkdocs/docs/api/json_sax/binary.md

@@ -23,7 +23,7 @@ It is safe to move the passed binary value.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse__binary.cpp"

docs/mkdocs/docs/api/json_sax/boolean.md

@@ -19,7 +19,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/end_array.md

@@ -14,7 +14,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/end_object.md

@@ -14,7 +14,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/key.md

@@ -23,7 +23,7 @@ It is safe to move the passed object key value.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/null.md

@@ -14,7 +14,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/number_float.md

@@ -22,7 +22,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/number_integer.md

@@ -19,7 +19,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/number_unsigned.md

@@ -19,7 +19,7 @@ Whether parsing should proceed.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/parse_error.md

@@ -27,7 +27,7 @@ Whether parsing should proceed (**must return `#!cpp false`**).
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/start_array.md

@@ -23,7 +23,7 @@ Binary formats may report the number of elements.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/start_object.md

@@ -23,7 +23,7 @@ Binary formats may report the number of elements.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/json_sax/string.md

@@ -23,7 +23,7 @@ It is safe to move the passed string value.
 
 ??? example
 
-    .The example below shows how the SAX interface is used.
+    The example below shows how the SAX interface is used.
 
     ```cpp
     --8<-- "examples/sax_parse.cpp"

docs/mkdocs/docs/api/macros/nlohmann_json_namespace.md

@@ -4,19 +4,34 @@
 #define NLOHMANN_JSON_NAMESPACE
 ```
 
-This macro evaluates to the full name of the `nlohmann` namespace, including
-the name of a versioned and ABI-tagged inline namespace. Use this macro to
-unambiguously refer to the `nlohmann` namespace.
+This macro evaluates to the full name of the `nlohmann` namespace, including  the name of a versioned and ABI-tagged
+inline namespace. Use this macro to unambiguously refer to the `nlohmann` namespace.
 
 ## Default definition
 
-The default value consists of a prefix, a version string, and optional ABI tags
-depending on whether ABI-affecting macros are defined (e.g.,
-[`JSON_DIAGNOSTICS`](json_diagnostics.md), and
+The default value consists of a prefix, a version string, and optional ABI tags depending on whether ABI-affecting
+macros are defined (e.g., [`JSON_DIAGNOSTICS`](json_diagnostics.md), and
 [`JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`](json_use_legacy_discarded_value_comparison.md)).
 
 When the macro is not defined, the library will define it to its default value.
 
+## Examples
+
+??? example
+
+    The example shows an example how to use `NLOHMANN_JSON_NAMESPACE` instead of just `nlohmann`, as well as shows
+    the value of `NLOHMANN_JSON_NAMESPACE`.
+
+    ```cpp
+    --8<-- "examples/nlohmann_json_namespace.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_namespace.output"
+    ```
+
 ## See also
 
 - [`NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END`](nlohmann_json_namespace_begin.md)

docs/mkdocs/docs/api/macros/nlohmann_json_namespace_begin.md

@@ -5,9 +5,8 @@
 #define NLOHMANN_JSON_NAMESPACE_END    // (2)
 ```
 
-These macros can be used to open and close the `nlohmann` namespace. They
-include an inline namespace used to differentiate symbols when linking multiple
-versions (including different ABI-affecting macros) of this library.
+These macros can be used to open and close the `nlohmann` namespace. They include an inline namespace used to
+differentiate symbols when linking multiple versions (including different ABI-affecting macros) of this library.
 
 1. Opens the namespace.
     ```cpp
@@ -25,11 +24,26 @@ versions (including different ABI-affecting macros) of this library.
 
 ## Default definition
 
-The default definitions open and close the `nlohmann` as well as an inline
-namespace.
+The default definitions open and close the `nlohmann` as well as an inline  namespace.
 
-When these macros are not defined, the library will define them to their
-default definitions.
+When these macros are not defined, the library will define them to their default definitions.
+
+## Examples
+
+??? example
+
+    The example shows an example how to use `NLOHMANN_JSON_NAMESPACE_BEGIN`/`NLOHMANN_JSON_NAMESPACE_END` from the
+    [How do I convert third-party types?](../../features/arbitrary_types.md#how-do-i-convert-third-party-types) page.
+
+    ```cpp
+    --8<-- "examples/nlohmann_json_namespace_begin.c++17.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/nlohmann_json_namespace_begin.c++17.output"
+    ```
 
 ## See also
 

docs/mkdocs/docs/api/operator_gtgt.md

@@ -21,8 +21,7 @@ the stream `i`
 ## Exceptions
 
 - Throws [`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token.
-- Throws [`parse_error.102`](../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate 
-  error.
+- Throws [`parse_error.102`](../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate error.
 - Throws [`parse_error.103`](../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails.
 
 ## Complexity