📝 add more API documentation

doc/docset/docSet.sql

@@ -36,6 +36,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('front', 'Method', 'api/basic_
 INSERT INTO searchIndex(name, type, path) VALUES ('get_allocator', 'Function', 'api/basic_json/get_allocator/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('input_format_t', 'Enum', 'api/basic_json/input_format_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('insert', 'Method', 'api/basic_json/insert/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('invalid_iterator', 'Class', 'api/basic_json/invalid_iterator/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('is_array', 'Method', 'api/basic_json/is_array/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('is_binary', 'Method', 'api/basic_json/is_binary/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('is_boolean', 'Method', 'api/basic_json/is_boolean/index.html');
@@ -70,7 +71,10 @@ INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json_pointer', 'Li
 INSERT INTO searchIndex(name, type, path) VALUES ('operator value_t', 'Operator', 'api/basic_json/operator_value_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_json', 'Class', 'api/ordered_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map', 'Class', 'api/ordered_map/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('out_of_range', 'Class', 'api/basic_json/out_of_range/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('other_error', 'Class', 'api/basic_json/other_error/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('parse', 'Function', 'api/basic_json/parse/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('parse_error', 'Class', 'api/basic_json/parse_error/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('parse_event_t', 'Enum', 'api/basic_json/parse_event_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('parser_callback_t', 'Type', 'api/basic_json/parser_callback_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('patch', 'Method', 'api/basic_json/patch/index.html');
@@ -81,6 +85,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('sax_parse', 'Function', 'api/
 INSERT INTO searchIndex(name, type, path) VALUES ('size', 'Method', 'api/basic_json/size/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('string_t', 'Type', 'api/basic_json/string_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('type', 'Method', 'api/basic_json/type/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('type_error', 'Class', 'api/basic_json/type_error/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('type_name', 'Method', 'api/basic_json/type_name/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('unflatten', 'Method', 'api/basic_json/unflatten/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('update', 'Method', 'api/basic_json/update/index.html');

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

@@ -1,4 +1,4 @@
-# basic_json::exception
+# basic_basic_json::exception
 
 ```cpp
 class exception : public std::exception;
@@ -9,32 +9,32 @@ member `id` for exception ids. It is used as the base class for all exceptions t
 class can hence be used as "wildcard" to catch exceptions, see example below.
 
 ```plantuml
-std::exception <|-- json::exception
+std::exception <|-- basic_json::exception
-json::exception <|-- json::parse_error
+basic_json::exception <|-- basic_json::parse_error
-json::exception <|-- json::invalid_iterator
+basic_json::exception <|-- basic_json::invalid_iterator
-json::exception <|-- json::type_error
+basic_json::exception <|-- basic_json::type_error
-json::exception <|-- json::out_of_range
+basic_json::exception <|-- basic_json::out_of_range
-json::exception <|-- json::other_error
+basic_json::exception <|-- basic_json::other_error
 
 interface std::exception {}
 
-class json::exception #FFFF00 {
+class basic_json::exception #FFFF00 {
     + const int id
     + const char* what() const
 }
 
-class json::parse_error {
+class basic_json::parse_error {
     + const std::size_t byte
 }
 ```
 
 Subclasses:
 
-- `parse_error` for exceptions indicating a parse error
+- [`parse_error`](parse_error.md) for exceptions indicating a parse error
-- `invalid_iterator` for exceptions indicating errors with iterators
+- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators
-- `type_error` for exceptions indicating executing a member function with a wrong type
+- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type
-- `out_of_range` for exceptions indicating access out of the defined range
+- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range
-- `other_error` for exceptions indicating other library errors
+- [`other_error`](other_error.md) for exceptions indicating other library errors
 
 ## Member functions
 

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

@@ -60,11 +60,11 @@ Todo
 ### Exceptions
 
 - [**exception**](exception.md) - general exception of the `basic_json` class
-- parse_error
+    - [**parse_error**](parse_error.md) - exception indicating a parse error
-- invalid_iterator
+    - [**invalid_iterator**](invalid_iterator.md) - exception indicating errors with iterators
-- type_error
+    - [**type_error**](type_error.md) - exception indicating executing a member function with a wrong type
-- out_of_range
+    - [**out_of_range**](out_of_range.md) - exception indicating access out of the defined range
-- other_error
+    - [**other_error**](other_error.md) - exception indicating other library errors
 
 ### Container types
 

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

@@ -0,0 +1,59 @@
+# basic_basic_json::invalid_iterator
+
+```cpp
+class invalid_iterator : public exception;
+```
+
+This exception is thrown if iterators passed to a library function do not match the expected semantics.
+
+Exceptions have ids 2xx.
+
+```plantuml
+std::exception <|-- basic_json::exception
+basic_json::exception <|-- basic_json::parse_error
+basic_json::exception <|-- basic_json::invalid_iterator
+basic_json::exception <|-- basic_json::type_error
+basic_json::exception <|-- basic_json::out_of_range
+basic_json::exception <|-- basic_json::other_error
+
+interface std::exception {}
+
+class basic_json::exception {
+    + const int id
+    + const char* what() const
+}
+
+class basic_json::parse_error {
+    + const std::size_t byte
+}
+
+class basic_json::invalid_iterator #FFFF00 {}
+```
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+
+## Example
+
+??? example
+
+    The following code shows how a `invalid_iterator` exception can be caught.
+    
+    ```cpp
+    --8<-- "examples/invalid_iterator.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/invalid_iterator.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

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

@@ -0,0 +1,59 @@
+# basic_basic_json::other_error
+
+```cpp
+class other_error : public exception;
+```
+
+This exception is thrown in case of errors that cannot be classified with the other exception types.
+
+Exceptions have ids 5xx.
+
+```plantuml
+std::exception <|-- basic_json::exception
+basic_json::exception <|-- basic_json::parse_error
+basic_json::exception <|-- basic_json::invalid_iterator
+basic_json::exception <|-- basic_json::type_error
+basic_json::exception <|-- basic_json::out_of_range
+basic_json::exception <|-- basic_json::other_error
+
+interface std::exception {}
+
+class basic_json::exception {
+    + const int id
+    + const char* what() const
+}
+
+class basic_json::parse_error {
+    + const std::size_t byte
+}
+
+class basic_json::other_error #FFFF00 {}
+```
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+
+## Example
+
+??? example
+
+    The following code shows how a `other_error` exception can be caught.
+    
+    ```cpp
+    --8<-- "examples/other_error.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/other_error.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

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

@@ -0,0 +1,60 @@
+# basic_basic_json::out_of_range
+
+```cpp
+class out_of_range : public exception;
+```
+
+This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for
+instance in case of array indices or nonexisting object keys.
+
+Exceptions have ids 4xx.
+
+```plantuml
+std::exception <|-- basic_json::exception
+basic_json::exception <|-- basic_json::parse_error
+basic_json::exception <|-- basic_json::invalid_iterator
+basic_json::exception <|-- basic_json::type_error
+basic_json::exception <|-- basic_json::out_of_range
+basic_json::exception <|-- basic_json::other_error
+
+interface std::exception {}
+
+class basic_json::exception {
+    + const int id
+    + const char* what() const
+}
+
+class basic_json::parse_error {
+    + const std::size_t byte
+}
+
+class basic_json::out_of_range #FFFF00 {}
+```
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+
+## Example
+
+??? example
+
+    The following code shows how a `out_of_range` exception can be caught.
+    
+    ```cpp
+    --8<-- "examples/out_of_range.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/out_of_range.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

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

@@ -0,0 +1,64 @@
+# basic_basic_json::parse_error
+
+```cpp
+class parse_error : public exception;
+```
+
+This exception is thrown by the library when a parse error occurs. Parse errors can occur during the deserialization of
+JSON text, BSON, CBOR, MessagePack, UBJSON, as well as when using JSON Patch.
+
+Exceptions have ids 1xx.
+
+```plantuml
+std::exception <|-- basic_json::exception
+basic_json::exception <|-- basic_json::parse_error
+basic_json::exception <|-- basic_json::invalid_iterator
+basic_json::exception <|-- basic_json::type_error
+basic_json::exception <|-- basic_json::out_of_range
+basic_json::exception <|-- basic_json::other_error
+
+interface std::exception {}
+
+class basic_json::exception {
+    + const int id
+    + const char* what() const
+}
+
+class basic_json::parse_error #FFFF00 {
+    + const std::size_t byte
+}
+```
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+- **byte** - byte index of the parse error
+
+## Note
+
+For an input with _n_ bytes, 1 is the index of the first character and _n_+1 is the index of the terminating null byte
+or the end of file. This also holds true when reading a byte vector for binary formats.
+
+## Example
+
+??? example
+
+    The following code shows how a `parse_error` exception can be caught.
+    
+    ```cpp
+    --8<-- "examples/parse_error.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse_error.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

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

@@ -0,0 +1,60 @@
+# basic_basic_json::type_error
+
+```cpp
+class type_error : public exception;
+```
+
+This exception is thrown in case of a type error; that is, a library function is executed on a JSON value whose type
+does not match the expected semantics.
+
+Exceptions have ids 3xx.
+
+```plantuml
+std::exception <|-- basic_json::exception
+basic_json::exception <|-- basic_json::parse_error
+basic_json::exception <|-- basic_json::invalid_iterator
+basic_json::exception <|-- basic_json::type_error
+basic_json::exception <|-- basic_json::out_of_range
+basic_json::exception <|-- basic_json::other_error
+
+interface std::exception {}
+
+class basic_json::exception {
+    + const int id
+    + const char* what() const
+}
+
+class basic_json::parse_error {
+    + const std::size_t byte
+}
+
+class basic_json::type_error #FFFF00 {}
+```
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+
+## Example
+
+??? example
+
+    The following code shows how a `type_error` exception can be caught.
+    
+    ```cpp
+    --8<-- "examples/type_error.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/type_error.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

doc/mkdocs/mkdocs.yml

@@ -109,6 +109,7 @@ nav:
         - api/basic_json/get_allocator.md
         - api/basic_json/input_format_t.md
         - api/basic_json/insert.md
+        - api/basic_json/invalid_iterator.md
         - api/basic_json/is_array.md
         - api/basic_json/is_binary.md
         - api/basic_json/is_boolean.md
@@ -139,7 +140,10 @@ nav:
         - api/basic_json/operator+=.md
         - api/basic_json/operator_literal_json.md
         - api/basic_json/operator_literal_json_pointer.md
+        - api/basic_json/out_of_range.md
+        - api/basic_json/other_error.md
         - api/basic_json/parse.md
+        - api/basic_json/parse_error.md
         - api/basic_json/parse_event_t.md
         - api/basic_json/parser_callback_t.md
         - api/basic_json/patch.md
@@ -154,6 +158,7 @@ nav:
         - api/basic_json/to_msgpack.md
         - api/basic_json/to_ubjson.md
         - api/basic_json/type.md
+        - api/basic_json/type_error.md
         - api/basic_json/type_name.md
         - api/basic_json/unflatten.md
         - api/basic_json/update.md