From 0356e0c75b566d50af3ac612e439944997a21f94 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Fri, 14 Aug 2020 13:05:16 +0200 Subject: [PATCH] :memo: add more API documentation --- doc/docset/docSet.sql | 5 ++ doc/mkdocs/docs/api/basic_json/exception.md | 28 ++++---- doc/mkdocs/docs/api/basic_json/index.md | 10 +-- .../docs/api/basic_json/invalid_iterator.md | 59 +++++++++++++++++ doc/mkdocs/docs/api/basic_json/other_error.md | 59 +++++++++++++++++ .../docs/api/basic_json/out_of_range.md | 60 +++++++++++++++++ doc/mkdocs/docs/api/basic_json/parse_error.md | 64 +++++++++++++++++++ doc/mkdocs/docs/api/basic_json/type_error.md | 60 +++++++++++++++++ doc/mkdocs/mkdocs.yml | 5 ++ 9 files changed, 331 insertions(+), 19 deletions(-) create mode 100644 doc/mkdocs/docs/api/basic_json/invalid_iterator.md create mode 100644 doc/mkdocs/docs/api/basic_json/other_error.md create mode 100644 doc/mkdocs/docs/api/basic_json/out_of_range.md create mode 100644 doc/mkdocs/docs/api/basic_json/parse_error.md create mode 100644 doc/mkdocs/docs/api/basic_json/type_error.md diff --git a/doc/docset/docSet.sql b/doc/docset/docSet.sql index edfa95a50..47d893e98 100644 --- a/doc/docset/docSet.sql +++ b/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'); diff --git a/doc/mkdocs/docs/api/basic_json/exception.md b/doc/mkdocs/docs/api/basic_json/exception.md index 1b9d81384..d6609ee1f 100644 --- a/doc/mkdocs/docs/api/basic_json/exception.md +++ b/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 -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 +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 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 -- `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 +- [`parse_error`](parse_error.md) for exceptions indicating a parse error +- [`invalid_iterator`](invalid_iterator.md) for exceptions indicating errors with iterators +- [`type_error`](type_error.md) for exceptions indicating executing a member function with a wrong type +- [`out_of_range`](out_of_range.md) for exceptions indicating access out of the defined range +- [`other_error`](other_error.md) for exceptions indicating other library errors ## Member functions diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 0e30eb832..55851ab33 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/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 -- invalid_iterator -- type_error -- out_of_range -- other_error + - [**parse_error**](parse_error.md) - exception indicating a parse error + - [**invalid_iterator**](invalid_iterator.md) - exception indicating errors with iterators + - [**type_error**](type_error.md) - exception indicating executing a member function with a wrong type + - [**out_of_range**](out_of_range.md) - exception indicating access out of the defined range + - [**other_error**](other_error.md) - exception indicating other library errors ### Container types diff --git a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md new file mode 100644 index 000000000..1a56c5281 --- /dev/null +++ b/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. diff --git a/doc/mkdocs/docs/api/basic_json/other_error.md b/doc/mkdocs/docs/api/basic_json/other_error.md new file mode 100644 index 000000000..fdaa29050 --- /dev/null +++ b/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. diff --git a/doc/mkdocs/docs/api/basic_json/out_of_range.md b/doc/mkdocs/docs/api/basic_json/out_of_range.md new file mode 100644 index 000000000..18a8e95ab --- /dev/null +++ b/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. diff --git a/doc/mkdocs/docs/api/basic_json/parse_error.md b/doc/mkdocs/docs/api/basic_json/parse_error.md new file mode 100644 index 000000000..305087ddb --- /dev/null +++ b/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. diff --git a/doc/mkdocs/docs/api/basic_json/type_error.md b/doc/mkdocs/docs/api/basic_json/type_error.md new file mode 100644 index 000000000..498fbd47b --- /dev/null +++ b/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. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 6c5cf37e3..115bfbde5 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/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