📝 add more documentation

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

@@ -0,0 +1,72 @@
+# basic_json::dump
+
+```cpp
+string_t dump(const int indent = -1,
+              const char indent_char = ' ',
+              const bool ensure_ascii = false,
+              const error_handler_t error_handler = error_handler_t::strict) const
+```
+
+Serialization function for JSON values. The function tries to mimic
+Python's `json.dumps()` function, and currently supports its `indent`
+and `ensure_ascii` parameters.
+    
+## Parameters
+
+`indent` (in)
+:   If indent is nonnegative, then array elements and object
+    members will be pretty-printed with that indent level. An indent level of
+    `0` will only insert newlines. `-1` (the default) selects the most compact
+    representation.
+
+`indent_char` (in)
+:   The character to use for indentation if `indent` is
+    greater than `0`. The default is ` ` (space).
+
+`ensure_ascii` (in)
+:   If `ensure_ascii` is true, all non-ASCII characters
+    in the output are escaped with `\uXXXX` sequences, and the result consists
+    of ASCII characters only.
+
+`error_handler` (in)
+:   how to react on decoding errors; there are three
+    possible values: `strict` (throws and exception in case a decoding error
+    occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD),
+    and `ignore` (ignore invalid UTF-8 sequences during serialization; all
+    bytes are copied to the output unchanged).
+    
+## Return value
+
+string containing the serialization of the JSON value
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no
+changes to any JSON value.
+
+## Complexity
+
+Linear.
+
+## Notes
+
+Binary values are serialized as object containing two keys:
+
+- "bytes": an array of bytes as integers
+- "subtype": the subtype as integer or `#!json null` if the binary has no subtype
+
+## Example
+
+The following example shows the effect of different `indent`,
+    `indent_char`, and `ensure_ascii` parameters to the result of the
+    serialization.
+
+```cpp
+--8<-- "examples/dump.cpp"
+```
+
+Output:
+
+```json
+--8<-- "examples/dump.output"
+```

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

@@ -0,0 +1,11 @@
+# Overview
+
+## Member functions
+
+### Object inspection
+
+- [dump](dump.md) - serialization
+
+## Static functions
+
+- [meta](meta.md) - returns version information on the library

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

@@ -0,0 +1,45 @@
+# basic_json::meta
+
+```cpp
+static basic_json meta();
+```
+
+This function returns a JSON object with information about the library,
+including the version number and information on the platform and compiler.
+    
+## Return value
+
+JSON object holding version information
+
+key         | description
+----------- | ---------------
+`compiler`  | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
+`copyright` | The copyright line for the library as string.
+`name`      | The name of the library as string.
+`platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
+`url`       | The URL of the project as string.
+`version`   | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no
+changes to any JSON value.
+
+## Complexity
+
+Constant.
+
+## Example
+
+The following code shows an example output of the `meta()`
+function.
+
+```cpp
+--8<-- "examples/meta.cpp"
+```
+
+Output:
+
+```json
+--8<-- "examples/meta.output"
+```

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:
+## Overview
-
-- 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.
 
@@ -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 |
 | -------- | ------------- | ----------- |

doc/mkdocs/mkdocs.yml

@@ -45,19 +45,23 @@ nav:
       - features/binary_formats/ubjson.md
     - features/binary_values.md
     - features/comments.md
-    - features/element_access.md
+    - Element Access:
+      - features/element_access/index.md
+      - features/element_access/unchecked_access.md
+      - features/element_access/checked_access.md
+      - features/element_access/default_value.md
     - features/iterators.md
     - features/json_pointer.md
     - features/json_patch.md
     - features/merge_patch.md
     - features/object_order.md
+    - Parsing:
+        - features/parsing/index.md
+        - features/parsing/parse_exceptions.md
+        - features/parsing/parser_callbacks.md
+        - features/parsing/sax_interface.md
     - features/enum_conversion.md
     - features/macros.md
-    - Parsing:
-      - features/parsing/index.md
-      - features/parsing/parse_exceptions.md
-      - features/parsing/parser_callbacks.md
-      - features/parsing/sax_interface.md
     - features/types.md
   - Integration:
     - integration/index.md
@@ -65,6 +69,11 @@ nav:
     - integration/package_managers.md
   - Doxygen:
     - doxygen/index.html
+  - API:
+      - basic_json:
+        - api/basic_json/index.md
+        - api/basic_json/dump.md
+        - api/basic_json/meta.md
 
 # Extras
 extra:
@@ -83,6 +92,7 @@ extra:
 # Extensions
 markdown_extensions:
   - admonition
+  - def_list
   - codehilite:
       guess_lang: false
   - toc: