📝 overwork macro documentation

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

@@ -13,11 +13,9 @@ header.
 
 ## Exceptions
 
-- `JSON_CATCH_USER(exception)`
+- [**JSON_CATCH_USER(exception)**<br>**JSON_THROW_USER(exception)**<br>**JSON_TRY_USER**](json_throw_user.md) - control exceptions
 - [**JSON_DIAGNOSTICS**](json_diagnostics.md) - control extended diagnostics
-- `JSON_NOEXCEPTION`
+- [**JSON_NOEXCEPTION**](json_noexception.md) - switch off exceptions
-- `JSON_THROW_USER(exception)`
-- `JSON_TRY_USER`
 
 ## Language support
 

doc/mkdocs/docs/api/macros/json_noexception.md

@@ -0,0 +1,32 @@
+# JSON_NOEXCEPTION
+
+```cpp
+#define JSON_NOEXCEPTION
+```
+
+Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try`
+is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by
+`#!cpp std::abort()`.
+
+The same effect is achieved by setting the compiler flag `-fno-exceptions`.
+
+## Default definition
+
+By default, the macro is not defined.
+
+```cpp
+#undef JSON_NOEXCEPTION
+```
+
+## Notes
+
+The explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
+available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
+
+## See also
+
+- [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions
+
+## Version history
+
+Added in version 2.1.0.

doc/mkdocs/docs/api/macros/json_skip_library_version_check.md

@@ -15,6 +15,23 @@ By default, the macro is not defined.
 #undef JSON_SKIP_LIBRARY_VERSION_CHECK
 ```
 
+## Notes
+
+!!! warning
+
+    Mixing different library versions in the same code can be a problem as the different versions may not be ABI
+    compatible.
+
+## Examples
+
+!!! example
+
+    The following warning will be shown in case a different version of the library was already included:
+
+    ```
+    Already included a different version of the library!
+    ```
+
 ## Version history
 
 Added in version 3.11.0.

doc/mkdocs/docs/api/macros/json_throw_user.md

@@ -0,0 +1,70 @@
+# JSON_CATCH_USER(exception), JSON_THROW_USER(exception), JSON_TRY_USER
+
+```cpp
+// (1)
+#define JSON_CATCH_USER(exception) /* value */
+// (2)
+#define JSON_THROW_USER(exception) /* value */
+// (3)
+#define JSON_TRY_USER /* value */
+```
+
+Controls how exceptions are handled by the library.
+
+1. This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library.
+   The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range`
+   exceptions internally to rethrow them as [`json::out_of_range`](../../home/exceptions.md#out-of-range) exceptions.
+   The macro is always followed by a scope.
+2. This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that
+   `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield
+   undefined behavior.
+3. This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope.
+
+## Default definition
+
+By default, the macros map to their respective C++ keywords:
+
+```cpp
+#define JSON_CATCH_USER(exception) catch(exception)
+#define JSON_THROW_USER(exception) throw exception
+#define JSON_TRY_USER              try
+```
+
+When exceptions are switched off, the `#!cpp try` block is executed unconditionally, and throwing exceptions is
+replaced by calling [`std::abort`](https://en.cppreference.com/w/cpp/utility/program/abort) to make reaching the
+`cpp throw` branch abort the process.
+
+```cpp
+#define JSON_THROW_USER(exception) std::abort()
+#define JSON_TRY_USER              if (true)
+#define JSON_CATCH_USER(exception) if (false)
+```
+
+## Examples
+
+??? example
+
+    The code below switches off exceptions and creates a log entry with a detailed error message in case of errors.
+
+    ```cpp
+    #include <iostream>
+    
+    #define JSON_TRY_USER if(true)
+    #define JSON_CATCH_USER(exception) if(false)
+    #define JSON_THROW_USER(exception)                           \
+        {std::clog << "Error in " << __FILE__ << ":" << __LINE__ \
+                   << " (function " << __FUNCTION__ << ") - "    \
+                   << (exception).what() << std::endl;           \
+         std::abort();}
+    
+    #include <nlohmann/json.hpp>
+    ```
+
+## See also
+
+- [Switch off exceptions](../../home/exceptions.md#switch-off-exceptions) for more information how to switch off exceptions
+- [JSON_NOEXCEPTION](JSON_NOEXCEPTION) - switch off exceptions
+
+## Version history
+
+- Added in version 3.1.0.

doc/mkdocs/docs/features/macros.md

@@ -11,29 +11,8 @@ See [full documentation of `JSON_ASSERT(x)`](../api/macros/json_assert.md).
 ## `JSON_CATCH_USER(exception)`
 
 This macro overrides [`#!cpp catch`](https://en.cppreference.com/w/cpp/language/try_catch) calls inside the library.
-The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range`
-exceptions internally to rethrow them as [`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The
-macro is always followed by a scope.
 
-See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
+See [full documentation of `JSON_CATCH_USER(exception)`](../api/macros/json_throw_user.md).
-
-!!! info "Default behavior"
-
-    When exceptions are enabled, the default value is
-    [`#!cpp catch(exception)`](https://en.cppreference.com/w/cpp/language/try_catch).
-
-    ```cpp
-    #define JSON_CATCH_USER(exception) catch(exception)
-    ```
-
-    When exceptions are switched off by the compiler, the default value is `#!cpp if (false)` to make the catch block
-    unreachable.
-
-    ```cpp
-    #define JSON_CATCH_USER(exception) if (false)
-    ```
-
-The macro was introduced in version 3.1.0.
 
 ## `JSON_DIAGNOSTICS`
 
@@ -70,24 +49,9 @@ See [full documentation of `JSON_HAS_FILESYSTEM` and `JSON_HAS_EXPERIMENTAL_FILE
 
 ## `JSON_NOEXCEPTION`
 
-Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try`
+Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`.
-is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by
-`#!cpp std::abort()`.
 
-!!! info "Default behavior"
+See [full documentation of `JSON_NOEXCEPTION`](../api/macros/json_noexception.md).
-
-    By default, the macro is not defined.
-
-    ```cpp
-    #undef JSON_NOEXCEPTION
-    ```
-
-The same effect is achieved by setting the compiler flag `-fno-exceptions`.
-
-Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
-available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
-
-The macro was introduced in version 2.1.0.
 
 ## `JSON_NO_IO`
 
@@ -113,54 +77,15 @@ See [full documentation of `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`](../api/macros
 
 ## `JSON_THROW_USER(exception)`
 
-This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that
+This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown.
-`JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield
-undefined behavior.
 
-!!! info "Default behavior"
+See [full documentation of `JSON_THROW_USER(exception)`](../api/macros/json_throw_user.md).
-
-    When exceptions are enabled, the default value is
-    [`#!cpp throw exception`](https://en.cppreference.com/w/cpp/language/throw).
-
-    ```cpp
-    #define JSON_THROW_USER(exception) throw exception
-    ```
-
-    When exceptions are switched off by the compiler, the default value is
-    [`#!cpp std::abort()`](https://en.cppreference.com/w/cpp/utility/program/abort) to make reaching the throw branch
-    abort the process.
-
-    ```cpp
-    #define JSON_THROW_USER(exception) std::abort()
-    ```
-
-See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
-
-The macro was introduced in version 3.1.0.
 
 ## `JSON_TRY_USER`
 
-This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope.
+This macro overrides `#!cpp try` calls inside the library.
 
-!!! info "Default behavior"
+See [full documentation of `JSON_TRY_USER`](../api/macros/json_throw_user.md).
-
-    When exceptions are enabled, the default value is
-    [`#!cpp try`](https://en.cppreference.com/w/cpp/language/try_catch).
-
-    ```cpp
-    #define JSON_TRY_USER try
-    ```
-
-    When exceptions are switched off by the compiler, the default value is `#!cpp if (true)` to unconditionally execute
-    the following code block.
-
-    ```cpp
-    #define JSON_TRY_USER if (true)
-    ```
-
-See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
-
-The macro was introduced in version 3.1.0.
 
 ## `JSON_USE_IMPLICIT_CONVERSIONS`
 

doc/mkdocs/docs/home/exceptions.md

@@ -28,9 +28,9 @@ class json::parse_error {
 
 ### Switch off exceptions
 
-Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol `JSON_NOEXCEPTION`. In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp catch`).
+Exceptions are used widely within the library. They can, however, be switched off with either using the compiler flag `-fno-exceptions` or by defining the symbol [`JSON_NOEXCEPTION`](../api/macros/json_noexception.md). In this case, exceptions are replaced by `abort()` calls. You can further control this behavior by defining `JSON_THROW_USER` (overriding `#!cpp throw`), `JSON_TRY_USER` (overriding `#!cpp try`), and `JSON_CATCH_USER` (overriding `#!cpp catch`).
 
-Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
+Note that [`JSON_THROW_USER`](../api/macros/json_throw_user.md) should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
 
 ??? example
 
@@ -52,6 +52,8 @@ Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or
 
 Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
 
+See [documentation of `JSON_TRY_USER`, `JSON_CATCH_USER` and `JSON_THROW_USER`](../api/macros/json_throw_user.md) for more information.
+
 ### 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.
@@ -88,6 +90,7 @@ As this global context comes at the price of storing one additional pointer per
 
     Now the exception message contains a JSON Pointer `/address/housenumber` that indicates which value has the wrong type.
 
+See [documentation of `JSON_DIAGNOSTICS`](../api/macros/json_diagnostics.md) for more information.
 
 ## Parse errors
 

doc/mkdocs/mkdocs.yml

@@ -234,17 +234,21 @@ nav:
       - macros:
         - 'Overview': api/macros/index.md
         - 'JSON_ASSERT(x)': api/macros/json_assert.md
+        - 'JSON_CATCH_USER': api/macros/json_throw_user.md
         - 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md
-        - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md
         - 'JSON_HAS_CPP_11': api/macros/json_has_cpp_11.md
         - 'JSON_HAS_CPP_14': api/macros/json_has_cpp_11.md
         - 'JSON_HAS_CPP_17': api/macros/json_has_cpp_11.md
         - 'JSON_HAS_CPP_20': api/macros/json_has_cpp_11.md
+        - 'JSON_HAS_EXPERIMENTAL_FILESYSTEM': api/macros/json_has_filesystem.md
         - 'JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md
-        - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
+        - 'JSON_NOEXCEPTION': api/macros/json_noexception.md
         - 'JSON_NO_IO': api/macros/json_no_io.md
         - 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md
         - 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
+        - 'JSON_THROW_USER': api/macros/json_throw_user.md
+        - 'JSON_TRY_USER': api/macros/json_throw_user.md
+        - 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
         - 'NLOHMANN_JSON_VERSION_MAJOR': api/macros/nlohmann_json_version_major.md
         - 'NLOHMANN_JSON_VERSION_MINOR': api/macros/nlohmann_json_version_major.md
         - 'NLOHMANN_JSON_VERSION_PATCH': api/macros/nlohmann_json_version_major.md