Merge pull request #2363 from nlohmann/issue2360 Fix and extend documentation of discarded values

diff --git a/doc/examples/parse__allow_exceptions.cpp b/doc/examples/parse__allow_exceptions.cpp
new file mode 100644
index 0000000..82449a5
--- /dev/null
+++ b/doc/examples/parse__allow_exceptions.cpp

@@ -0,0 +1,36 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // an invalid JSON text
+    std::string text = R"(
+    {
+        "key": "value without closing quotes
+    }
+    )";
+
+    // parse with exceptions
+    try
+    {
+        json j = json::parse(text);
+    }
+    catch (json::parse_error& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    // parse without exceptions
+    json j = json::parse(text, nullptr, false);
+
+    if (j.is_discarded())
+    {
+        std::cout << "the input is invalid JSON" << std::endl;
+    }
+    else
+    {
+        std::cout << "the input is valid JSON: " << j << std::endl;
+    }
+}

diff --git a/doc/examples/parse__allow_exceptions.link b/doc/examples/parse__allow_exceptions.link
new file mode 100644
index 0000000..386dfe8
--- /dev/null
+++ b/doc/examples/parse__allow_exceptions.link

@@ -0,0 +1 @@
+<a target="_blank" href="https://wandbox.org/permlink/2TsG4VSg87HsRQC9"><b>online</b></a>
\ No newline at end of file

diff --git a/doc/examples/parse__allow_exceptions.output b/doc/examples/parse__allow_exceptions.output
new file mode 100644
index 0000000..d650824
--- /dev/null
+++ b/doc/examples/parse__allow_exceptions.output

@@ -0,0 +1,2 @@
+[json.exception.parse_error.101] parse error at line 4, column 0: syntax error while parsing value - invalid string: control character U+000A (LF) must be escaped to \u000A or \n; last read: '"value without closing quotes<U+000A>'
+the input is invalid JSON

diff --git a/doc/mkdocs/docs/api/basic_json/exception.md b/doc/mkdocs/docs/api/basic_json/exception.md
index d6609ee..deedae5 100644
--- a/doc/mkdocs/docs/api/basic_json/exception.md
+++ b/doc/mkdocs/docs/api/basic_json/exception.md

@@ -1,4 +1,4 @@
-# basic_basic_json::exception
+# basic_json::exception
 
 ```cpp
 class exception : public std::exception;

diff --git a/doc/mkdocs/docs/api/basic_json/from_bson.md b/doc/mkdocs/docs/api/basic_json/from_bson.md
index bf218cd..6df74f3 100644
--- a/doc/mkdocs/docs/api/basic_json/from_bson.md
+++ b/doc/mkdocs/docs/api/basic_json/from_bson.md

@@ -52,7 +52,7 @@
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
-`value_t::discarded`.
+`value_t::discarded`.  The latter can be checked with [`is_discarded`](is_discarded.md).
 
 ## Exception safety
 

diff --git a/doc/mkdocs/docs/api/basic_json/from_cbor.md b/doc/mkdocs/docs/api/basic_json/from_cbor.md
index 138229a..ec186fc 100644
--- a/doc/mkdocs/docs/api/basic_json/from_cbor.md
+++ b/doc/mkdocs/docs/api/basic_json/from_cbor.md

@@ -59,7 +59,7 @@
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
-`value_t::discarded`.
+`value_t::discarded`.  The latter can be checked with [`is_discarded`](is_discarded.md).
 
 ## Exception safety
 

diff --git a/doc/mkdocs/docs/api/basic_json/from_msgpack.md b/doc/mkdocs/docs/api/basic_json/from_msgpack.md
index 18649c1..9f68524 100644
--- a/doc/mkdocs/docs/api/basic_json/from_msgpack.md
+++ b/doc/mkdocs/docs/api/basic_json/from_msgpack.md

@@ -52,7 +52,7 @@
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
-`value_t::discarded`.
+`value_t::discarded`.  The latter can be checked with [`is_discarded`](is_discarded.md).
 
 ## Exception safety
 

diff --git a/doc/mkdocs/docs/api/basic_json/from_ubjson.md b/doc/mkdocs/docs/api/basic_json/from_ubjson.md
index 91c22f0..f6213f2 100644
--- a/doc/mkdocs/docs/api/basic_json/from_ubjson.md
+++ b/doc/mkdocs/docs/api/basic_json/from_ubjson.md

@@ -52,7 +52,7 @@
 ## Return value
 
 deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
-`value_t::discarded`.
+`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
 
 ## Exception safety
 

diff --git a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md
index 1a56c52..b11b27d 100644
--- a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md
+++ b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md

@@ -1,4 +1,4 @@
-# basic_basic_json::invalid_iterator
+# basic_json::invalid_iterator
 
 ```cpp
 class invalid_iterator : public exception;

diff --git a/doc/mkdocs/docs/api/basic_json/is_discarded.md b/doc/mkdocs/docs/api/basic_json/is_discarded.md
index d233e6c..b733f62 100644
--- a/doc/mkdocs/docs/api/basic_json/is_discarded.md
+++ b/doc/mkdocs/docs/api/basic_json/is_discarded.md

@@ -4,9 +4,12 @@
 constexpr bool is_discarded() const noexcept;
 ```
 
-This function returns true if and only if the JSON value was discarded during parsing with a callback function (see
-[`parser_callback_t`](parser_callback_t.md)).
-    
+This function returns `#!cpp true` for a JSON value if either:
+
+- the value was discarded during parsing with a callback function (see [`parser_callback_t`](parser_callback_t.md)), or
+- the value is the result of parsing invalid JSON with parameter `allow_exceptions` set to `#!cpp false`; see
+  [`parse`](parse.md) for more information.
+
 ## Return value
 
 `#!cpp true` if type is discarded, `#!cpp false` otherwise.
@@ -21,6 +24,30 @@
 
 ## Notes
 
+!!! note
+
+    Discarded values are never compared equal with [`operator==`](operator_eq.md). That is, checking whether a JSON
+    value `j` is discarded will only work via:
+    
+    ```cpp
+    j.is_discarded()
+    ```
+    
+    because
+    
+    ```cpp
+    j == json::value_t::discarded
+    ```
+    
+    will always be `#!cpp false`.
+
+!!! note
+
+    When a value is discarded by a callback function (see [`parser_callback_t`](parser_callback_t.md)) during parsing,
+    then it is removed when it is part of a structured value. For instance, if the second value of an array is discared,
+    instead of `#!json [null, discarded, false]`, the array `#!json [null, false]` is returned. Only if the top-level
+    value is discarded, the return value of the `parse` call is discarded.
+
 This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur
 during parsing, but will be removed when inside a structured value or replaced by null in other cases.
 

diff --git a/doc/mkdocs/docs/api/basic_json/operator_eq.md b/doc/mkdocs/docs/api/basic_json/operator_eq.md
index d087d99..34cf553 100644
--- a/doc/mkdocs/docs/api/basic_json/operator_eq.md
+++ b/doc/mkdocs/docs/api/basic_json/operator_eq.md

@@ -12,11 +12,10 @@
 
 Compares two JSON values for equality according to the following rules:
 
-- Two JSON values are equal if (1) they are from the same type and (2) their stored values are the same according to
-  their respective `operator==`.
+- Two JSON values are equal if (1) they are not discarded, (2) they are from the same type, and (3) their stored values
+  are the same according to their respective `operator==`.
 - Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always
   treated as unequal.
-- Two JSON null values are equal.
 
 ## Template parameters
 
@@ -45,11 +44,19 @@
 
 ## Notes
 
-- Floating-point 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
-  [comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
-  could be used, for instance
+!!! note
 
+    - 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
+
+    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
+    [comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39)
+    could be used, for instance
+    
     ```cpp
     template<typename T, typename = typename std::enable_if<std::is_floating_point<T>::value, T>::type>
     inline bool is_same(T a, T b, T epsilon = std::numeric_limits<T>::epsilon()) noexcept
@@ -78,8 +85,6 @@
     }
     ```
 
-- NaN values never compare equal to themselves or to other NaN values.
-
 ## Example
 
 ??? example

diff --git a/doc/mkdocs/docs/api/basic_json/other_error.md b/doc/mkdocs/docs/api/basic_json/other_error.md
index fdaa290..492b2d4 100644
--- a/doc/mkdocs/docs/api/basic_json/other_error.md
+++ b/doc/mkdocs/docs/api/basic_json/other_error.md

@@ -1,4 +1,4 @@
-# basic_basic_json::other_error
+# basic_json::other_error
 
 ```cpp
 class other_error : public exception;

diff --git a/doc/mkdocs/docs/api/basic_json/out_of_range.md b/doc/mkdocs/docs/api/basic_json/out_of_range.md
index 18a8e95..47ead87 100644
--- a/doc/mkdocs/docs/api/basic_json/out_of_range.md
+++ b/doc/mkdocs/docs/api/basic_json/out_of_range.md

@@ -1,4 +1,4 @@
-# basic_basic_json::out_of_range
+# basic_json::out_of_range
 
 ```cpp
 class out_of_range : public exception;

diff --git a/doc/mkdocs/docs/api/basic_json/parse.md b/doc/mkdocs/docs/api/basic_json/parse.md
index 11e420d..1f991b3 100644
--- a/doc/mkdocs/docs/api/basic_json/parse.md
+++ b/doc/mkdocs/docs/api/basic_json/parse.md

@@ -61,7 +61,7 @@
 ## Return value
 
 Deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be
-`value_t::discarded`.
+`value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md).
 
 ## Exception safety
 
@@ -79,7 +79,7 @@
 
 ## Examples
 
-??? example
+??? example "Parsing from a charater array"
 
     The example below demonstrates the `parse()` function reading from an array.
 
@@ -93,7 +93,7 @@
     --8<-- "examples/parse__array__parser_callback_t.output"
     ```
 
-??? example
+??? example "Parsing from a string"
 
     The example below demonstrates the `parse()` function with and without callback function.
 
@@ -107,7 +107,7 @@
     --8<-- "examples/parse__string__parser_callback_t.output"
     ```
 
-??? example
+??? example "Parsing from an input stream"
 
     The example below demonstrates the `parse()` function with and without callback function.
 
@@ -121,7 +121,7 @@
     --8<-- "examples/parse__istream__parser_callback_t.output"
     ```
 
-??? example
+??? example "Parsing from a contiguous container"
 
     The example below demonstrates the `parse()` function reading from a contiguous container.
 
@@ -135,6 +135,20 @@
     --8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
     ```
 
+??? example "Effect of `allow_exceptions` parameter"
+
+    The example below demonstrates the effect of the `allow_exceptions` parameter in the ´parse()` function.
+
+    ```cpp
+    --8<-- "examples/parse__allow_exceptions.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse__allow_exceptions.output"
+    ```
+
 ## Version history
 
 - Added in version 1.0.0.

diff --git a/doc/mkdocs/docs/api/basic_json/parse_error.md b/doc/mkdocs/docs/api/basic_json/parse_error.md
index 305087d..de0ee40 100644
--- a/doc/mkdocs/docs/api/basic_json/parse_error.md
+++ b/doc/mkdocs/docs/api/basic_json/parse_error.md

@@ -1,4 +1,4 @@
-# basic_basic_json::parse_error
+# basic_json::parse_error
 
 ```cpp
 class parse_error : public exception;

diff --git a/doc/mkdocs/docs/api/basic_json/type_error.md b/doc/mkdocs/docs/api/basic_json/type_error.md
index 498fbd4..ea0154e 100644
--- a/doc/mkdocs/docs/api/basic_json/type_error.md
+++ b/doc/mkdocs/docs/api/basic_json/type_error.md

@@ -1,4 +1,4 @@
-# basic_basic_json::type_error
+# basic_json::type_error
 
 ```cpp
 class type_error : public exception;