📝 add more documentation

doc/mkdocs/docs/features/element_access.md

@@ -0,0 +1,108 @@
+# Element Access
+
+There are many ways elements in a JSON value can be accessed:
+
+- unchecked access via `operator[]`
+- checked access via `at`
+- checked access with default value via `value`
+- iterators
+- JSON pointers
+
+## Unchecked access via `operator[]`
+
+### Overview
+
+Elements in a JSON object and a JSON array can be accessed via `#!cpp operator[]` similar to a `#!cpp std::map` and a `#!cpp std::vector`, respectively.
+
+??? example
+
+    Consider the following JSON value:
+    
+    ```json
+    {
+        "name": "Mary Smith",
+        "age": 42,
+        "hobbies": ["hiking", "reading"]
+    }
+    ```
+    
+    Assume the value is parsed to a `json` variable `j`.
+
+    | expression | value |
+    | ---------- | ----- |
+    | `#!cpp j`  | `#!json {"name": "Mary Smith", "age": 42, "hobbies": ["hiking", "reading"]}` |
+    | `#!cpp j["name"]`  | `#!json "Mary Smith"` |
+    | `#!cpp j["age"]`  | `#!json 42` |
+    | `#!cpp j["hobbies"]`  | `#!json ["hiking", "reading"]` |
+    | `#!cpp j["hobbies"][0]`  | `#!json "hiking"` |
+    | `#!cpp j["hobbies"][1]`  | `#!json "reading"` |
+
+The return value is a reference, so it can be modify the original value. In case the passed object key is non-existing, a `#!json null` value is inserted which can be immediately be overwritten.
+
+??? example
+
+    ```cpp
+    j["name"] = "John Smith";
+    j["maidenName"] = "Jones";
+    ```
+    
+    This code produces the following JSON value:
+    
+    ```json
+    {
+        "name": "John Smith",
+        "maidenName": "Jones",
+        "age": 42,
+        "hobbies": ["hiking", "reading"]
+    }
+    ```
+
+When accessing an invalid index (i.e., and index greater than or equal to the array size), the JSON array is resized such that the passed index is the new maximal index. Intermediate values are filled with `#!json null`.
+
+??? example
+
+    ```cpp
+    j["hobbies"][0] = "running";
+    j["hobbies"][3] = "cooking";
+    ```
+    
+    This code produces the following JSON value:
+    
+    ```json
+    {
+        "name": "John Smith",
+        "maidenName": "Jones",
+        "age": 42,
+        "hobbies": ["running", "reading", null, "cooking"]
+    }
+    ```
+
+### Notes
+
+!!! info "Design rationale"
+
+    The library behaves differently to `#!cpp std::vector` and `#!cpp std::map`:
+    
+    - `#!cpp std::vector::operator[]` never inserts a new element.
+    - `#!cpp std::map::operator[]` is not available for const values.
+    
+    The type `#!cpp json` wraps all JSON value types. It would be impossible to remove `operator[]` for const objects. At the same time, inserting elements for non-const objects is really convenient as it avoids awkward `insert` calls. To this end, we decided to have an inserting non-const behavior for both arrays and objects.
+
+!!! info
+
+    The access is unchecked. In case the passed object key does not exist or the passed array index is invalid, no exception is thrown.
+
+!!! danger
+
+    - It is **undefined behavior** to access a const object with a non-existing key.
+    - It is **undefined behavior** to access a const array with an invalid index.
+    - In debug mode, an **assertion** will fire in both cases. You can disable assertions by defining the preprocessor symbol `#!cpp NDEBUG` or redefine the macro [`JSON_ASSERT(x)`](macros.md#json_assertx).
+
+### Summary
+
+| scenario | non-const value | const value |
+| -------- | ------------- | ----------- |
+| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
+| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
+| access to non-existing object key | reference to newly inserted `#!json null` value is returned | **undefined behavior**; assertion in debug mode |
+| access to invalid array index | reference to newly inserted `#!json null` value is returned; any index between previous maximal index and passed index are filled with `#!json null` | **undefined behavior**; assertion in debug mode |

doc/mkdocs/docs/features/macros.md

@@ -2,6 +2,10 @@
 
 Some aspects of the library can be configured by defining preprocessor macros before including the `json.hpp` header.
 
+## `JSON_ASSERT(x)`
+
+The default value is `#!cpp assert(x)`.
+
 ## `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.

doc/mkdocs/mkdocs.yml

@@ -45,6 +45,7 @@ nav:
       - features/binary_formats/ubjson.md
     - features/binary_values.md
     - features/comments.md
+    - features/element_access.md
     - features/iterators.md
     - features/json_pointer.md
     - features/json_patch.md