:memo: add more API documentation
diff --git a/doc/docset/docSet.sql b/doc/docset/docSet.sql index 3775752..edfa95a 100644 --- a/doc/docset/docSet.sql +++ b/doc/docset/docSet.sql
@@ -8,11 +8,13 @@ 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 ('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');
diff --git a/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md b/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md new file mode 100644 index 0000000..ea417de --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
@@ -0,0 +1,21 @@ +# 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.
diff --git a/doc/mkdocs/docs/api/basic_json/exception.md b/doc/mkdocs/docs/api/basic_json/exception.md new file mode 100644 index 0000000..1b9d813 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/exception.md
@@ -0,0 +1,65 @@ +# 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.
diff --git a/doc/mkdocs/docs/api/basic_json/from_cbor.md b/doc/mkdocs/docs/api/basic_json/from_cbor.md index afe91a1..138229a 100644 --- a/doc/mkdocs/docs/api/basic_json/from_cbor.md +++ b/doc/mkdocs/docs/api/basic_json/from_cbor.md
@@ -53,7 +53,8 @@ : 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
diff --git a/doc/mkdocs/docs/api/basic_json/get_allocator.md b/doc/mkdocs/docs/api/basic_json/get_allocator.md new file mode 100644 index 0000000..d4133af --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/get_allocator.md
@@ -0,0 +1,15 @@ +# basic_json::get_allocator + +```cpp +static allocator_type get_allocator(); +``` + +Returns the allocator associated with the container. + +## Return value + +associated allocator + +## Version history + +- Unknown.
diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index a5651df..0e30eb8 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md
@@ -52,14 +52,14 @@ - [**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 @@ ## 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
diff --git a/doc/mkdocs/docs/api/basic_json/input_format_t.md b/doc/mkdocs/docs/api/basic_json/input_format_t.md new file mode 100644 index 0000000..783085d --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/input_format_t.md
@@ -0,0 +1,32 @@ +# 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 (Binary JSON) + +## Version history + +- Added in version 3.2.0.
diff --git a/doc/mkdocs/docs/api/basic_json/sax_parse.md b/doc/mkdocs/docs/api/basic_json/sax_parse.md index 0bb7458..7a6dbad 100644 --- a/doc/mkdocs/docs/api/basic_json/sax_parse.md +++ b/doc/mkdocs/docs/api/basic_json/sax_parse.md
@@ -55,7 +55,8 @@ : 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)
diff --git a/doc/mkdocs/docs/home/exceptions.md b/doc/mkdocs/docs/home/exceptions.md index afa505b..0475f53 100644 --- a/doc/mkdocs/docs/home/exceptions.md +++ b/doc/mkdocs/docs/home/exceptions.md
@@ -454,7 +454,6 @@ [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 @@ 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.
diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 4384b3d..6c5cf37 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml
@@ -83,6 +83,7 @@ - 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 @@ - 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 @@ - 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