From ce6adc447a08c0fd7a1855778d6549034a61b86c Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 13 Aug 2020 14:04:08 +0200 Subject: [PATCH] :memo: add more API documentation --- doc/docset/docSet.sql | 3 ++ doc/mkdocs/docs/api/basic_json/index.md | 6 ++-- .../docs/api/basic_json/operator\"\"_json.md" | 32 +++++++++++++++++++ .../basic_json/operator\"\"_json_pointer.md" | 32 +++++++++++++++++++ doc/mkdocs/docs/api/json_pointer.md | 24 ++++++++++++++ doc/mkdocs/mkdocs.yml | 3 ++ 6 files changed, 97 insertions(+), 3 deletions(-) create mode 100644 "doc/mkdocs/docs/api/basic_json/operator\"\"_json.md" create mode 100644 "doc/mkdocs/docs/api/basic_json/operator\"\"_json_pointer.md" create mode 100644 doc/mkdocs/docs/api/json_pointer.md diff --git a/doc/docset/docSet.sql b/doc/docset/docSet.sql index 287c61961..4ac547a0b 100644 --- a/doc/docset/docSet.sql +++ b/doc/docset/docSet.sql @@ -47,6 +47,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('is_string', 'Method', 'api/ba INSERT INTO searchIndex(name, type, path) VALUES ('is_structured', 'Method', 'api/basic_json/is_structured/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('items', 'Method', 'api/basic_json/items/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('json', 'Class', 'api/json/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('json_pointer', 'Class', 'api/json_pointer/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('max_size', 'Method', 'api/basic_json/max_size/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('merge_patch', 'Method', 'api/basic_json/merge_patch/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('meta', 'Function', 'api/basic_json/meta/index.html'); @@ -60,6 +61,8 @@ INSERT INTO searchIndex(name, type, path) VALUES ('operator+=', 'Operator', 'api INSERT INTO searchIndex(name, type, path) VALUES ('operator=', 'Operator', 'api/basic_json/operator=/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('operator==', 'Operator', 'api/basic_json/operator==/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('operator[]', 'Operator', 'api/basic_json/operator[]/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json', 'Literal', 'api/basic_json/operator%22%22_json/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json_pointer', 'Literal', 'api/basic_json/operator%22%22_json_pointer/index.html'); 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'); diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 67448d61e..145b04836 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -49,7 +49,7 @@ Todo ## Member types - [**value_t**](value_t.md) - the JSON type enumeration -- json_pointer +- [**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 @@ -245,8 +245,8 @@ Access to the JSON value ## Literals -- operator""_json -- operator""_json_pointer +- [**operator""_json**](operator%22%22_json.md) - user-defined string literal for JSON values +- [**operator""_json_pointer**](operator%22%22_json_pointer.md) - user-defined string literal for JSON pointers ## Helper classes diff --git "a/doc/mkdocs/docs/api/basic_json/operator\"\"_json.md" "b/doc/mkdocs/docs/api/basic_json/operator\"\"_json.md" new file mode 100644 index 000000000..8c96067b9 --- /dev/null +++ "b/doc/mkdocs/docs/api/basic_json/operator\"\"_json.md" @@ -0,0 +1,32 @@ +# basic_json::operator""_json + +```cpp +json operator "" _json(const char* s, std::size_t n) +``` + +This operator implements a user-defined string literal for JSON objects. It can be used by adding `#!cpp _json` to a +string literal and returns a [`json`](../json.md) object if no parse error occurred. + +## Parameters + +`s` (in) +: a string representation of a JSON object + +`n` (in) +: length of string `s` + +## Return value + +[`json`](../json.md) value parsed from `s` + +## Exceptions + +The function can throw anything that [`parse(s, s+n)`](parse.md) would throw. + +## Complexity + +Linear. + +## Version history + +- Added in version 1.0.0. diff --git "a/doc/mkdocs/docs/api/basic_json/operator\"\"_json_pointer.md" "b/doc/mkdocs/docs/api/basic_json/operator\"\"_json_pointer.md" new file mode 100644 index 000000000..0316b7c61 --- /dev/null +++ "b/doc/mkdocs/docs/api/basic_json/operator\"\"_json_pointer.md" @@ -0,0 +1,32 @@ +# basic_json::operator""_json_pointer + +```cpp +json_pointer operator "" _json_pointer(const char* s, std::size_t n) +``` + +This operator implements a user-defined string literal for JSON Pointers. It can be used by adding `#!cpp _json_pointer` +to a string literal and returns a [`json_pointer`](../json_pointer.md) object if no parse error occurred. + +## Parameters + +`s` (in) +: a string representation of a JSON Pointer + +`n` (in) +: length of string `s` + +## Return value + +[`json_pointer`](../json_pointer.md) value parsed from `s` + +## Exceptions + +The function can throw anything that [`json_pointer::json_pointer`](../json_pointer.md) would throw. + +## Complexity + +Linear. + +## Version history + +- Added in version 2.0.0. diff --git a/doc/mkdocs/docs/api/json_pointer.md b/doc/mkdocs/docs/api/json_pointer.md new file mode 100644 index 000000000..5aa0399cd --- /dev/null +++ b/doc/mkdocs/docs/api/json_pointer.md @@ -0,0 +1,24 @@ +# json_pointer + +```cpp +template +class json_pointer; +``` + +## Template parameters + +`BasicJsonType` +: a specialization of [`basic_json`](basic_json/index.md) + +## Member functions + +- (constructor) +- **to_string** - return a string representation of the JSON pointer +- **operator std::string**- return a string representation of the JSON pointer +- **operator/=** - append to the end of the JSON pointer +- **operator/** - create JSON Pointer by appending +- **parent_pointer** - returns the parent of this JSON pointer +- **pop_back** - remove last reference token +- **back** - return last reference token +- **push_back** - append an unescaped token at the end of the pointer +- **empty** - return whether pointer points to the root document diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index f9fd0c328..35c75265d 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -129,6 +129,8 @@ nav: - api/basic_json/operator==.md - api/basic_json/operator!=.md - api/basic_json/operator+=.md + - api/basic_json/operator""_json.md + - api/basic_json/operator""_json_pointer.md - api/basic_json/parse.md - api/basic_json/parse_event_t.md - api/basic_json/parser_callback_t.md @@ -146,6 +148,7 @@ nav: - api/basic_json/value.md - api/basic_json/value_t.md - api/json.md + - api/json_pointer.md - api/ordered_map.md - api/ordered_json.md