Overwork documentation (#3444)

* 📝 overwork macro documentation

* 📝 address review comments

* 🔧 add style check to Makefile

* 🙈 overwork .gitignore

* 📌 Pygments 2.12.0 is broken

* ✏️ fix links

* 🚸 adjust output to cppcheck

* 📝 add titles to more admonitions

* ✏️ fix typos

* 📝 document future behavior change

doc/mkdocs/docs/api/basic_json/back.md

@@ -35,9 +35,9 @@ Constant.
 
 ## Notes
 
-!!! danger
+!!! info "Precondition"
 
-    Calling `back` on an empty array or object is undefined behavior and is **guarded by an assertion**!
+    The array or object must not be empty. Calling `back` on an empty array or object yields undefined behavior.
 
 ## Examples
 

doc/mkdocs/docs/api/basic_json/basic_json.md

@@ -250,17 +250,15 @@ basic_json(basic_json&& other) noexcept;
 
     !!! info "Preconditions"
 
-        - Iterators `first` and `last` must be initialized. **This precondition is enforced with an assertion (see
-          warning).** If assertions are switched off, a violation of this precondition yields undefined behavior.
+        - Iterators `first` and `last` must be initialized. **This precondition is enforced with a
+          [runtime assertion](../../features/assertions.md).
         - Range `[first, last)` is valid. Usually, this precondition cannot be checked efficiently. Only certain edge
           cases are detected; see the description of the exceptions above. A violation of this precondition yields
           undefined behavior.
     
-    !!! warning
+    !!! danger "Runtime assertion"
 
-        A precondition is enforced with a runtime assertion that will result in calling `std::abort` if this
-        precondition is not met. Assertions can be disabled by defining `NDEBUG` at compile time. See
-        <https://en.cppreference.com/w/cpp/error/assert> for more information.
+        A precondition is enforced with a [runtime assertion](../../features/assertions.md).
     
 - Overload 8:
 

doc/mkdocs/docs/api/basic_json/front.md

@@ -28,9 +28,9 @@ Constant.
 
 ## Notes
 
-!!! danger
+!!! info "Precondition"
 
-    Calling `front` on an empty array or object is undefined behavior and is **guarded by an assertion**!
+    The array or object must not be empty. Calling `front` on an empty array or object yields undefined behavior.
 
 ## Examples
 

doc/mkdocs/docs/api/basic_json/get.md

@@ -90,7 +90,7 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
 
 ## Notes
 
-!!! warning
+!!! danger "Undefined behavior"
 
     Writing data to the pointee (overload 3) of the result yields an undefined state.
 

doc/mkdocs/docs/api/basic_json/get_ptr.md

@@ -33,7 +33,7 @@ Constant.
 
 ## Notes
 
-!!! warning
+!!! danger "Undefined behavior"
 
     Writing data to the pointee of the result yields an undefined state.
 

doc/mkdocs/docs/api/basic_json/get_ref.md

@@ -16,7 +16,7 @@ Implicit reference access to the internally stored JSON value. No copies are mad
 :   reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
     [`string_t`](string_t.md), [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
     [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
-    Enforced by static assertion.
+    Enforced by a static assertion.
 
 ## Return value
 
@@ -38,7 +38,7 @@ Constant.
 
 ## Notes
 
-!!! warning
+!!! danger "Undefined behavior"
 
     Writing data to the referee of the result yields an undefined state.
 

doc/mkdocs/docs/api/basic_json/index.md

@@ -292,7 +292,7 @@ Access to the JSON value
 - [**std::hash<basic_json>**](std_hash.md) - return a hash value for a JSON object
 - [**std::swap<basic_json>**](std_swap.md) - exchanges the values of two JSON objects
 
-## Example
+## Examples
 
 ??? example
 

doc/mkdocs/docs/api/basic_json/is_discarded.md

@@ -24,7 +24,7 @@ Constant.
 
 ## Notes
 
-!!! note
+!!! note "Comparisons"
 
     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:
@@ -41,7 +41,7 @@ Constant.
     
     will always be `#!cpp false`.
 
-!!! note
+!!! note "Removal during parsing with callback functions"
 
     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 discarded,

doc/mkdocs/docs/api/basic_json/items.md

@@ -63,7 +63,7 @@ Constant.
 When iterating over an array, `key()` will return the index of the element as string (see example). For primitive types
 (e.g., numbers), `key()` returns an empty string.
 
-!!! warning
+!!! danger "Lifetime issues"
 
     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.

doc/mkdocs/docs/api/basic_json/meta.md

@@ -45,6 +45,10 @@ Constant.
     --8<-- "examples/meta.output"
     ```
 
+## See also
+
+- [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md) - library version information
+
 ## Version history
 
 - Added in version 2.1.0.

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

@@ -8,7 +8,7 @@ using object_comparator_t = std::less<>;            // since C++14
 
 The comparator used in [`object_t`](object_t.md).
 
-When C++14 is detected, a transparent com parator is used which, when combined with perfect forwarding on find() and
+When C++14 is detected, a transparent comparator is used which, when combined with perfect forwarding on find() and
 count() calls, prevents unnecessary string construction.
 
 ## Version history

doc/mkdocs/docs/api/basic_json/operator[].md

@@ -74,10 +74,11 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ## Notes
 
-!!! danger
+!!! danger "Undefined behavior and runtime assertions"
 
     1. If the element with key `idx` does not exist, the behavior is undefined.
-    2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by an assertion**!
+    2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by a
+       [runtime assertion](../../features/assertions.md)**!
 
 1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the
    array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In

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

@@ -27,33 +27,44 @@ Linear in the size of the JSON value.
 
 ## Notes
 
-By default `JSON_EXPLICIT` defined to the empty string, so the signature is:
+!!! note "Definition of `JSON_EXPLICIT`"
 
-```cpp
-template<typename ValueType>
-operator ValueType() const;
-```
+    By default `JSON_EXPLICIT` is defined to the empty string, so the signature is:
+    
+    ```cpp
+    template<typename ValueType>
+    operator ValueType() const;
+    ```
+    
+    If [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) is set to `0`,
+    `JSON_EXPLICIT` is defined to `#!cpp explicit`:
 
-If [`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) is set to `0`,
-`JSON_EXPLICIT` is defined to `#!cpp explicit`:
+    ```cpp
+    template<typename ValueType>
+    explicit operator ValueType() const;
+    ```
+    
+    That is, implicit conversions can be switched off by defining
+    [`JSON_USE_IMPLICIT_CONVERSIONS`](../macros/json_use_implicit_conversions.md) to `0`.
 
-```cpp
-template<typename ValueType>
-explicit operator ValueType() const;
-```
+!!! info "Future behavior change"
+
+    Implicit conversions will be switched off by default in the next major release of the library. That is,
+    `JSON_EXPLICIT` will be set to `#!cpp explicit` by default.
+
+    You can prepare existing code by already defining
+    [`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).
 
-That is, implicit conversions can be switched off by defining
-[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
 
 ## Examples
 
 ??? example
 
-    The example below shows several conversions from JSON values
-    to other types. There a few things to note: (1) Floating-point numbers can
-    be converted to integers, (2) A JSON array can be converted to a standard
-    `std::vector<short>`, (3) A JSON object can be converted to C++
-    associative containers such as `std::unordered_map<std::string, json>`.
+    The example below shows several conversions from JSON values to other types. There are a few things to note: (1)
+    Floating-point numbers can be converted to integers, (2) A JSON array can be converted to a standard
+    `std::vector<short>`, (3) A JSON object can be converted to C++ associative containers such as
+    `std::unordered_map<std::string, json>`.
         
     ```cpp
     --8<-- "examples/operator__ValueType.cpp"

doc/mkdocs/docs/api/basic_json/value.md

@@ -36,7 +36,7 @@ ValueType value(const json_pointer& ptr,
     }
     ```
 
-!!! note
+!!! note "Differences to `at` and `operator[]`"
 
     - Unlike [`at`](at.md), this function does not throw if the given `key`/`ptr` was not found.
     - Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by