📝 add documentation for macros

doc/mkdocs/docs/features/arbitrary_types.md

@@ -81,6 +81,43 @@ Some important things:
 * You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.
 
 
+## Simplify your life with macros
+
+If you just want to serialize/deserialize some structs, the `to_json`/`from_json` functions can be a lot of boilerplate.
+
+There are two macros to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object:
+
+- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the namespace of the class/struct to create code for.
+- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the class/struct to create code for. This macro can also access private members.
+
+In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.
+
+??? example
+
+    The `to_json`/`from_json` functions for the `person` struct above can be created with:
+
+    ```cpp
+    namespace ns {
+        NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(person, name, address, age)
+    }
+    ```
+
+    Here is an example with private members, where `NLOHMANN_DEFINE_TYPE_INTRUSIVE` is needed:
+
+    ```cpp
+    namespace ns {
+        class address {
+          private:
+            std::string street;
+            int housenumber;
+            int postcode;
+
+          public:
+            NLOHMANN_DEFINE_TYPE_INTRUSIVE(address, street, housenumber, postcode)
+        };
+    }
+    ```
+
 ## How do I convert third-party types?
 
 This requires a bit more advanced technique. But first, let's see how this conversion mechanism works:

doc/mkdocs/docs/features/macros.md

@@ -0,0 +1,55 @@
+# Supported Macros
+
+Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header.
+
+## `JSON_CATCH_USER(exception)`
+
+This macro overrides `#!cpp 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.
+
+## `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`.
+
+## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`
+
+When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
+
+## `JSON_THROW_USER(exception)`
+
+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.
+
+See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
+
+## `JSON_TRY_USER`
+
+This macro overrides `#!cpp try` calls inside the library. It has no arguments and is always followed by a scope.
+
+See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
+
+## `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.
+
+The macro is to be defined inside of the class/struct to create code for. Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members.
+The first parameter is the name of the class/struct, and all remaining parameters name the members.
+
+See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example.
+
+## `NLOHMANN_DEFINE_TYPE_NON_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.
+
+The macro is to be defined inside of the namespace of the class/struct to create code for. Private members cannot be accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios.
+The first parameter is the name of the class/struct, and all remaining parameters name the members.
+
+See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example.
+
+## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)`
+
+This macro simplifies the serialization/deserialization of enum types. See [Specializing enum conversion](enum_conversion.md) for more information.

doc/mkdocs/docs/home/exceptions.md

@@ -32,6 +32,24 @@ Exceptions are used widely within the library. They can, however, be switched of
 
 Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
 
+??? 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>
+    ```
+
 ## Parse errors
 
 This exception is thrown by the library when a parse error occurs. Parse errors

doc/mkdocs/mkdocs.yml

@@ -49,6 +49,7 @@ nav:
     - features/json_patch.md
     - features/merge_patch.md
     - features/enum_conversion.md
+    - features/macros.md
     - Parsing:
       - features/parsing/index.md
       - features/parsing/parse_exceptions.md