📝 add more documentation

doc/mkdocs/docs/features/element_access/checked_access.md

@@ -0,0 +1,77 @@
+# Checked access: at
+
+## Overview
+
+The `#!cpp at()` member function performs checked access; that is, it returns a reference to the desired value if it exists and throws a [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) otherwise.
+
+??? 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.at("name")`  | `#!json "Mary Smith"` |
+    | `#!cpp j.at("age")`  | `#!json 42` |
+    | `#!cpp j.at("hobbies")`  | `#!json ["hiking", "reading"]` |
+    | `#!cpp j.at("hobbies").at(0)`  | `#!json "hiking"` |
+    | `#!cpp j.at("hobbies").at(1)`  | `#!json "reading"` |
+
+The return value is a reference, so it can be modify the original value.
+
+??? example
+
+    ```cpp
+    j.at("name") = "John Smith";
+    ```
+    
+    This code produces the following JSON value:
+    
+    ```json
+    {
+        "name": "John Smith",
+        "age": 42,
+        "hobbies": ["hiking", "reading"]
+    }
+    ```
+
+When accessing an invalid index (i.e., and index greater than or equal to the array size) or the passed object key is non-existing, an exception is thrown.
+
+??? example
+
+    ```cpp
+    j.at("hobbies").at(3) = "cooking";
+    ```
+    
+    This code produces the following exception:
+    
+    ```
+    [json.exception.out_of_range.401] array index 3 is out of range
+    ```
+
+## Notes
+
+
+!!! failure "Exceptions"
+
+    - `at` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error304) is thrown.
+    - [`basic_json::out_of_range` exception](../../home/exceptions.md#out-of-range) exceptions are thrown if the provided key is not found in an object or the provided index is invalid.
+
+## 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 | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
+| access to invalid array index | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |

doc/mkdocs/docs/features/element_access/default_value.md

@@ -0,0 +1,32 @@
+# Access with default value: value
+
+## Overview
+
+In many situations such as configuration files, missing values are not exceptional, but may be treated as if a default value was present.
+
+??? example
+
+    Consider the following JSON value:
+    
+    ```json
+    {
+        "logOutput": "result.log",
+        "append": true
+    }
+    ```
+    
+    Assume the value is parsed to a `json` variable `j`.
+
+    | expression | value |
+    | ---------- | ----- |
+    | `#!cpp j`  | `#!json {"logOutput": "result.log", "append": true}` |
+    | `#!cpp j.value("logOutput", "logfile.log")`  | `#!json "result.log"` |
+    | `#!cpp j.value("append", true)`  | `#!json true` |
+    | `#!cpp j.value("append", false)`  | `#!json true` |
+    | `#!cpp j.value("logLevel", "verbose")`  | `#!json "verbose"` |
+
+## Note
+
+!!! failure "Exceptions"
+
+    - `value` can only be used with objects. For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error306) is thrown.

doc/mkdocs/docs/features/element_access/index.md

@@ -0,0 +1,9 @@
+# Overview
+
+There are many ways elements in a JSON value can be accessed:
+
+- unchecked access via [`operator[]`](unchecked_access.md)
+- checked access via [`at`](checked_access.md)
+- access with default value via [`value`](default_value.md)
+- iterators
+- JSON pointers

doc/mkdocs/docs/features/element_access/unchecked_access.md

@@ -1,16 +1,6 @@
-# Element Access
+# Unchecked access: operator[]
 
-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
+## 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.
 
@@ -77,7 +67,7 @@ When accessing an invalid index (i.e., and index greater than or equal to the ar
     }
     ```
 
-### Notes
+## Notes
 
 !!! info "Design rationale"
 
@@ -96,9 +86,13 @@ When accessing an invalid index (i.e., and index greater than or equal to the ar
 
     - 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).
+    - 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
+!!! failure "Exceptions"
+
+    `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown.
+
+## Summary
 
 | scenario | non-const value | const value |
 | -------- | ------------- | ----------- |