Overwork documentation (#4516)

docs/mkdocs/docs/features/arbitrary_types.md

@@ -75,7 +75,7 @@ Likewise, when calling `template get<your_type>()` or `get_to(your_type&)`, the
 Some important things:
 
 * Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined).
-* Those methods **MUST** be available (e.g., proper headers must be included) everywhere you use these conversions. Look at [issue 1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise.
+* Those methods **MUST** be available (e.g., proper headers must be included) everywhere you use these conversions. Look at [#1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise.
 * When using `template get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). (There is a way to bypass this requirement described later.)
 * In function `from_json`, use function [`at()`](../api/basic_json/at.md) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
 * You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.

docs/mkdocs/docs/features/assertions.md

@@ -103,29 +103,38 @@ behavior and yields a runtime assertion.
     Assertion failed: (m_object != nullptr), function operator++, file iter_impl.hpp, line 368.
     ```
 
-### Reading from a null `FILE` pointer
+## Changes
 
-Reading from a null `#!cpp FILE` pointer is undefined behavior and yields a runtime assertion. This can happen when
-calling `#!cpp std::fopen` on a nonexistent file.
+### Reading from a null `FILE` or `char` pointer
 
-??? example "Example 4: Uninitialized iterator"
+Reading from a null `#!cpp FILE` or `#!cpp char` pointer in C++ is undefined behavior.  Until version 3.11.4, this
+library asserted that the pointer was not `nullptr` using a runtime assertion. If assertions were disabled, this would
+result in undefined behavior. Since version 3.11.4, this library checks for `nullptr` and throws a
+[`parse_error.101`](../home/exceptions.md#jsonexceptionparse_error101) to prevent the undefined behavior.
+
+??? example "Example 4: Reading from null pointer"
 
     The following code will trigger an assertion at runtime:
 
     ```cpp
+    #include <iostream>
     #include <nlohmann/json.hpp>
     
     using json = nlohmann::json;
     
     int main()
     {
-      std::FILE* f = std::fopen("nonexistent_file.json", "r");
-      json j = json::parse(f);
+        std::FILE* f = std::fopen("nonexistent_file.json", "r");
+        try {
+            json j = json::parse(f);
+        } catch (std::exception& e) {
+            std::cerr << e.what() << std::endl;
+        }
     }
     ```
 
     Output:
 
     ```
-    Assertion failed: (m_file != nullptr), function file_input_adapter, file input_adapters.hpp, line 55.
+    [json.exception.parse_error.101] parse error: attempting to parse an empty input; check that your input string or stream contains the expected JSON
     ```

docs/mkdocs/docs/features/binary_values.md

@@ -10,17 +10,19 @@ serialized JSON text if they have been created manually or via a binary format.
 
 ## API for binary values
 
-```plantuml
-class json::binary_t {
-    -- setters --
+```mermaid
+classDiagram
+
+class binary_t ["json::binary_t"] {
     +void set_subtype(std::uint64_t subtype)
     +void clear_subtype()
-    -- getters --
     +std::uint64_t subtype() const
     +bool has_subtype() const
 }
 
-"std::vector<uint8_t>" <|-- json::binary_t
+class vector ["std::vector<uint8_t>"]
+
+vector <|-- binary_t
 ```
 
 By default, binary values are stored as `std::vector<std::uint8_t>`. This type can be changed by providing a template

docs/mkdocs/docs/features/comments.md

@@ -5,9 +5,9 @@ This library does not support comments *by default*. It does so for three reason
 1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
 2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
 
-    >     I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.  I know that the lack of comments makes some people sad, but it shouldn't. 
+    > I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.  I know that the lack of comments makes some people sad, but it shouldn't. 
 
-    >     Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
+    > Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
 
 3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
 

docs/mkdocs/docs/features/iterators.md

@@ -100,7 +100,7 @@ for (auto& [key, val] : j_object.items())
     
 !!! warning
 
-    Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See <https://github.com/nlohmann/json/issues/2040> for more information.
+    Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See [#2040](https://github.com/nlohmann/json/issues/2040) for more information.
 
 ### Reverse iteration order
 

docs/mkdocs/docs/features/macros.md

@@ -100,6 +100,11 @@ When defined to `0`, implicit conversions are switched off. By default, implicit
 
 See [full documentation of `JSON_USE_IMPLICIT_CONVERSIONS`](../api/macros/json_use_implicit_conversions.md).
 
+## `NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE(type, base_type, member...)`
+## `NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT(type, base_type, member...)`
+## `NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE(type, base_type, member...)`
+## `NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, base_type, member...)`
+
 ## `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

docs/mkdocs/docs/features/namespace.md

@@ -30,15 +30,16 @@ nlohmann::json_abi_diag_v3_11_2
 Several incompatibilities have been observed. Amongst the most common ones is linking code compiled with different
 definitions of [`JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md). This is illustrated in the diagram below.
 
-```plantuml
-[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=0] as [json]
-[**nlohmann_json (v3.10.5)**\nJSON_DIAGNOSTICS=1] as [json_diag]
-[**some_library**] as [library]
-[**application**] as [app]
-
-[library] ..|> [json]
-[app] ..|> [json_diag]
-[app] ..|>[library]
+```mermaid
+graph
+    json["<strong>nlohmann_json (v3.10.5)</strong><br>JSON_DIAGNOSTICS=0"]
+    json_diag["<strong>nlohmann_json (v3.10.5)</strong><br>JSON_DIAGNOSTICS=1"]
+    library["<strong>some library</strong>"]
+    app["<strong>application</strong>"]
+    
+    library --> json
+    app --> json_diag
+    app --> library
 ```
 
 In releases prior to 3.11.0, mixing any version of the JSON library with different `JSON_DIAGNOSTICS` settings would

docs/mkdocs/docs/features/parsing/sax_interface.md

@@ -2,27 +2,30 @@
 
 The library uses a SAX-like interface with the following functions:
 
-```plantuml
-interface json::sax_t {
-    + {abstract} bool null()
+```mermaid
+classDiagram
 
-    + {abstract} bool boolean(bool val)
-
-    + {abstract} bool number_integer(number_integer_t val)
-    + {abstract} bool number_unsigned(number_unsigned_t val)
-
-    + {abstract} bool number_float(number_float_t val, const string_t& s)
-
-    + {abstract} bool string(string_t& val)
-    + {abstract} bool binary(binary_t& val)
-
-    + {abstract} bool start_object(std::size_t elements)
-    + {abstract} bool end_object()
-    + {abstract} bool start_array(std::size_t elements)
-    + {abstract} bool end_array()
-    + {abstract} bool key(string_t& val)
-
-    + {abstract} bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex)
+class sax_t ["json::sax_t"] {
+    <<interface>>
+    +bool null()*
+    
+    +bool boolean(bool val)*
+    
+    +bool number_integer(number_integer_t val)*
+    +bool number_unsigned(number_unsigned_t val)*
+    
+    +bool number_float(number_float_t val, const string_t& s)*
+    
+    +bool string(string_t& val)*
+    +bool binary(binary_t& val)*
+    
+    +bool start_object(std::size_t elements)*
+    +bool end_object()*
+    +bool start_array(std::size_t elements)*
+    +bool end_array()*
+    +bool key(string_t& val)*
+    
+    +bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex)*
 }
 ```
 

docs/mkdocs/docs/features/types/index.md

@@ -19,8 +19,11 @@ Note there are three different types for numbers - when parsing JSON text, the b
 
 ## Storage
 
-```plantuml
-enum value_t {
+```mermaid
+classDiagram
+
+class value_t {
+    <<enumeration>>
     null
     object
     array
@@ -33,7 +36,8 @@ enum value_t {
     discarded
 }
 
-class json_value << (U,orchid) >> {
+class json_value {
+    <<union>>
     object_t* object
     array_t* array
     string_t* string
@@ -45,17 +49,15 @@ class json_value << (U,orchid) >> {
 }
 
 class basic_json {
-    -- type and value --
-    value_t m_type
-    json_value m_value
-    -- derived types --
-    + <u>typedef</u> object_t
-    + <u>typedef</u> array_t
-    + <u>typedef</u> binary_t
-    + <u>typedef</u> boolean_t
-    + <u>typedef</u> number_integer_t
-    + <u>typedef</u> number_unsigned_t
-    + <u>typedef</u> number_float_t
+    -value_t m_type
+    -json_value m_value
+    +typedef object_t
+    +typedef array_t
+    +typedef binary_t
+    +typedef boolean_t
+    +typedef number_integer_t
+    +typedef number_unsigned_t
+    +typedef number_float_t
 }
 
 basic_json .. json_value