📝 add more API documentation

doc/docset/docSet.sql

@@ -8,11 +8,13 @@ INSERT INTO searchIndex(name, type, path) VALUES ('array', 'Function', 'api/basi
 INSERT INTO searchIndex(name, type, path) VALUES ('array_t', 'Type', 'api/basic_json/array_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('at', 'Method', 'api/basic_json/at/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('back', 'Method', 'api/basic_json/back/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/basic_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Constructor', 'api/basic_json/basic_json/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('begin', 'Method', 'api/basic_json/begin/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('binary', 'Function', 'api/basic_json/binary/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('boolean_t', 'Type', 'api/basic_json/boolean_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('cbegin', 'Method', 'api/basic_json/cbegin/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('cbor_tag_handler_t', 'Enum', 'api/basic_json/cbor_tag_handler_t/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('cend', 'Method', 'api/basic_json/cend/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('clear', 'Method', 'api/basic_json/clear/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('contains', 'Method', 'api/basic_json/contains/index.html');
@@ -27,10 +29,12 @@ INSERT INTO searchIndex(name, type, path) VALUES ('empty', 'Method', 'api/basic_
 INSERT INTO searchIndex(name, type, path) VALUES ('end', 'Method', 'api/basic_json/end/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('erase', 'Method', 'api/basic_json/erase/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('error_handler_t', 'Enum', 'api/basic_json/error_handler_t/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('exception', 'Class', 'api/basic_json/exception/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('find', 'Method', 'api/basic_json/find/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('flatten', 'Method', 'api/basic_json/flatten/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('front', 'Method', 'api/basic_json/front/index.html');
-INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/basic_json/index.html');
+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 ('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');

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

+# basic_json::cbor_tag_handler_t
+
+```cpp
+enum class cbor_tag_handler_t
+{
+    error,
+    ignore
+};
+```
+
+This enumeration is used in the [`from_cbor`](from_cbor.md) function to choose how to treat tags:
+
+error
+:   throw a `parse_error` exception in case of a tag
+
+ignore
+:   ignore tags
+
+## Version history
+
+- Added in version 3.9.0.

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

+# basic_json::exception
+
+```cpp
+class exception : public std::exception;
+```
+
+This class is an extension of [`std::exception`](https://en.cppreference.com/w/cpp/error/exception) objects with a
+member `id` for exception ids. It is used as the base class for all exceptions thrown by the `basic_json` class. This
+class can hence be used as "wildcard" to catch exceptions, see example below.
+
+```plantuml
+std::exception <|-- json::exception
+json::exception <|-- json::parse_error
+json::exception <|-- json::invalid_iterator
+json::exception <|-- json::type_error
+json::exception <|-- json::out_of_range
+json::exception <|-- json::other_error
+
+interface std::exception {}
+
+class json::exception #FFFF00 {
+    + const int id
+    + const char* what() const
+}
+
+class json::parse_error {
+    + const std::size_t byte
+}
+```
+
+Subclasses:
+
+- `parse_error` for exceptions indicating a parse error
+- `invalid_iterator` for exceptions indicating errors with iterators
+- `type_error` for exceptions indicating executing a member function with a wrong type
+- `out_of_range` for exceptions indicating access out of the defined range
+- `other_error` for exceptions indicating other library errors
+
+## Member functions
+
+- **what** - returns explanatory string
+
+## Member variables
+
+- **id** - the id of the exception
+
+## Example
+
+??? example
+
+    The following code shows how arbitrary library exceptions can be caught.
+    
+    ```cpp
+    --8<-- "examples/exception.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/exception.output"
+    ```
+
+## Version history
+
+- Since version 3.0.0.

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

@@ -53,7 +53,8 @@ Deserializes a given input to a JSON value using the CBOR (Concise Binary Object
 :   whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
 
 `tag_handler` (in)
-:   how to treat CBOR tags (optional, `error` by default)
+:   how to treat CBOR tags (optional, `error` by default); see [`cbor_tag_handler_t`](cbor_tag_handler_t.md) for more
+    information
 
 ## Return value
 

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

+# basic_json::get_allocator
+
+```cpp
+static allocator_type get_allocator();
+```
+
+Returns the allocator associated with the container.
+    
+## Return value
+
+associated allocator
+
+## Version history
+
+- Unknown.

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

@@ -52,14 +52,14 @@ Todo
 - [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
 - json_serializer
 - [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
-- cbor_tag_handler_t
+- [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
 - initializer_list_t
-- input_format_t
+- [**input_format_t**](input_format_t.md) - type to choose the format to parse
 - json_sax_t
 
 ### Exceptions
 
-- exception
+- [**exception**](exception.md) - general exception of the `basic_json` class
 - parse_error
 - invalid_iterator
 - type_error
@@ -225,7 +225,7 @@ Access to the JSON value
 ## Static functions
 
 - [**meta**](meta.md) - returns version information on the library
-- get_allocator - returns the allocator associated with the container
+- [**get_allocator**](get_allocator.md) - returns the allocator associated with the container
 
 ### Binary formats
 

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

+# basic_json::input_format_t
+
+```cpp
+enum class input_format_t {
+    json,
+    cbor,
+    msgpack,
+    ubjson,
+    bson
+};
+```
+
+This enumeration is used in the [`sax_parse`](sax_parse.md) function to choose the input format to parse:
+
+json
+:   JSON (JavaScript Object Notation)
+
+cbor
+:   CBOR (Concise Binary Object Representation)
+
+msgpack
+:   MessagePack
+
+ubjson
+:   UBJSON (Universal Binary JSON)
+
+bson
+:   BSON (Bin­ary JSON)
+
+## Version history
+
+- Added in version 3.2.0.

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

@@ -55,7 +55,8 @@ The SAX event lister must follow the interface of `json_sax`.
 :   SAX event listener
 
 `format` (in)
-:    the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by default)
+:    the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by default), see
+     [`input_format_t`](input_format_t.md) for more information
 
 `strict` (in)
 :   whether the input has to be consumed completely (optional, `#!cpp true` by default)

doc/mkdocs/docs/home/exceptions.md

@@ -454,7 +454,6 @@ Cannot get value for iterator: Either the iterator belongs to a null value or it
     [json.exception.invalid_iterator.214] cannot get value
     ```
 
-
 ## Type errors
 
 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.
@@ -684,7 +683,6 @@ The dynamic type of the object cannot be represented in the requested serializat
 
     Encapsulate the JSON value in an object. That is, instead of serializing `#!json true`, serialize `#!json {"value": true}`
 
-
 ## Out of range
 
 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.

doc/mkdocs/mkdocs.yml

@@ -83,6 +83,7 @@ nav:
         - api/basic_json/binary.md
         - api/basic_json/boolean_t.md
         - api/basic_json/cbegin.md
+        - api/basic_json/cbor_tag_handler_t.md
         - api/basic_json/cend.md
         - api/basic_json/clear.md
         - api/basic_json/contains.md
@@ -97,6 +98,7 @@ nav:
         - api/basic_json/end.md
         - api/basic_json/erase.md
         - api/basic_json/error_handler_t.md
+        - api/basic_json/exception.md
         - api/basic_json/find.md
         - api/basic_json/flatten.md
         - api/basic_json/from_bson.md
@@ -104,6 +106,8 @@ nav:
         - api/basic_json/from_msgpack.md
         - api/basic_json/from_ubjson.md
         - api/basic_json/front.md
+        - api/basic_json/get_allocator.md
+        - api/basic_json/input_format_t.md
         - api/basic_json/insert.md
         - api/basic_json/is_array.md
         - api/basic_json/is_binary.md