📝 update documentation

doc/examples/diagnostics_extended.cpp

@@ -0,0 +1,22 @@
+#include <iostream>
+
+# define JSON_DIAGNOSTICS 1
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    json j;
+    j["address"]["street"] = "Fake Street";
+    j["address"]["housenumber"] = "12";
+
+    try
+    {
+        int housenumber = j["address"]["housenumber"];
+    }
+    catch (json::exception& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+}

doc/examples/diagnostics_extended.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/pbz3ULoJ4maRnV8N"><b>online</b></a>

doc/examples/diagnostics_extended.output

@@ -0,0 +1 @@
+[json.exception.type_error.302] (/address/housenumber) type must be number, but is string

doc/examples/diagnostics_standard.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    json j;
+    j["address"]["street"] = "Fake Street";
+    j["address"]["housenumber"] = "12";
+
+    try
+    {
+        int housenumber = j["address"]["housenumber"];
+    }
+    catch (json::exception& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+}

doc/examples/diagnostics_standard.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/fWfQhHzG03P6PAcC"><b>online</b></a>

doc/examples/diagnostics_standard.output

@@ -0,0 +1 @@
+[json.exception.type_error.302] type must be number, but is string

doc/mkdocs/docs/features/macros.md

@@ -12,6 +12,14 @@ This macro overrides `#!cpp catch` calls inside the library. The argument is the
 
 See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
 
+## `JSON_DIAGNOSTICS`
+
+This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable (default).
+
+When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example.
+
+The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets `JSON_DIAGNOSTICS` accordingly.
+
 ## `JSON_NOEXCEPTION`
 
 Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`.
@@ -56,6 +64,8 @@ When defined to `0`, implicit conversions are switched off. By default, implicit
     auto s = j.get<std::string>();
     ```
 
+Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
+
 ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)`
 
 This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object.

doc/mkdocs/docs/home/exceptions.md

@@ -50,6 +50,45 @@ Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or
     #include <nlohmann/json.hpp>
     ```
 
+### Extended diagnostic messages
+
+Exceptions in the library are thrown in the local context of the JSON value they are detected. This makes detailed 
+diagnostics messages, and hence debugging, difficult.
+
+??? example
+
+    ```cpp
+    --8<-- "examples/diagnostics_standard.cpp"
+    ```
+    
+    Output:
+
+    ```
+    --8<-- "examples/diagnostics_standard.output"
+    ```
+
+    This exception can be hard to debug if storing the value `#!c "12"` and accessing it is further apart.
+
+To create better diagnostics messages, each JSON value needs a pointer to its parent value such that a global context (i.e., a path from the root value to the value that lead to the exception) can be created. That global context is provided as [JSON Pointer](../features/json_pointer.md).
+
+As this global context comes at the price of storing one additional pointer per JSON value and runtime overhead to maintain the parent relation, extended diagnostics are disabled by default. They can, however, be enabled by defining the preprocessor symbol [`JSON_DIAGNOSTICS`](../features/macros.md#json_diagnostics) to `1` before including `json.hpp`.
+
+??? example
+
+    ```cpp
+    --8<-- "examples/diagnostics_extended.cpp"
+    ```
+    
+    Output:
+
+    ```
+    --8<-- "examples/diagnostics_extended.output"
+    ```
+
+    Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.
+
+
+
 ## Parse errors
 
 This exception is thrown by the library when a parse error occurs. Parse errors

doc/mkdocs/docs/home/license.md

@@ -4,7 +4,7 @@
 
 The class is licensed under the [MIT License](https://opensource.org/licenses/MIT):
 
-Copyright © 2013-2020 [Niels Lohmann](https://nlohmann.me)
+Copyright © 2013-2021 [Niels Lohmann](https://nlohmann.me)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: