📝 add more API documentation

doc/docset/docSet.sql

@@ -4,6 +4,7 @@ CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path);
 
 -- API
 INSERT INTO searchIndex(name, type, path) VALUES ('accept', 'Function', 'api/basic_json/accept/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('adl_serializer', 'Class', 'api/adl_serializer/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('array', 'Function', 'api/basic_json/array/index.html');
 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');
@@ -43,6 +44,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('get_allocator', 'Function', '
 INSERT INTO searchIndex(name, type, path) VALUES ('get_binary', 'Method', 'api/basic_json/get_binary/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('get_ptr', 'Method', 'api/basic_json/get_ptr/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('get_ref', 'Method', 'api/basic_json/get_ref/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('get_to', 'Method', 'api/basic_json/get_to/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');
@@ -62,6 +64,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('is_structured', 'Method', 'ap
 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 ('json_serializer', 'Type', 'api/basic_json/json_serializer/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');

doc/mkdocs/docs/api/adl_serializer.md

@@ -0,0 +1,31 @@
+# adl_serializer
+
+```cpp
+template<typename, typename>
+struct adl_serializer;
+```
+
+Serializer that uses ADL ([Argument-Dependent Lookup](https://en.cppreference.com/w/cpp/language/adl)) to choose
+`to_json`/`from_json` functions from the types' namespaces.
+
+It is implemented similar to
+
+```cpp
+template<typename ValueType>
+struct adl_serializer {
+    template<typename BasicJsonType>
+    static void to_json(BasicJsonType& j, const T& value) {
+        // calls the "to_json" method in T's namespace
+    }
+
+    template<typename BasicJsonType>
+    static void from_json(const BasicJsonType& j, T& value) {
+        // same thing, but with the "from_json" method
+    }
+};
+```
+
+## Member functions
+
+- **from_json** - convert a JSON value to any value type
+- **to_json** - convert any value type to a JSON value

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

@@ -73,8 +73,9 @@ constexpr const PointerType get_ptr() const noexcept;
 
 `PointerType`
 :   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
-    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or [`number_unsigned`](number_unsigned.md),
+    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
-    [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). Other types will not compile.
+    [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
+    Other types will not compile.
 
 ## Return value
 

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

@@ -14,8 +14,9 @@ Implicit pointer access to the internally stored JSON value. No copies are made.
 
 `PointerType`
 :   pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md),
-    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or [`number_unsigned`](number_unsigned.md),
+    [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
-    [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). Other types will not compile.
+    [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
+    Other types will not compile.
 
 ## Return value
 

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

@@ -15,7 +15,7 @@ Implicit reference access to the internally stored JSON value. No copies are mad
 `ReferenceType`
 :   reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md),
     [`string_t`](string_t.md), [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or
-    [`number_unsigned`](number_unsigned.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
+    [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md).
     Enforced by static assertion.
 
 ## Return value

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

@@ -0,0 +1,58 @@
+# basic_json::get_to
+
+```cpp
+template<typename ValueType>
+ValueType& get_to(ValueType& v) const noexcept(
+    noexcept(JSONSerializer<ValueType>::from_json(
+        std::declval<const basic_json_t&>(), v)))
+```
+
+Explicit type conversion between the JSON value and a compatible value. The value is filled into the input parameter by
+calling the `json_serializer<ValueType>` `from_json()` method.
+
+The function is equivalent to executing
+```cpp
+ValueType v;
+JSONSerializer<ValueType>::from_json(*this, v);
+```
+
+This overloads is chosen if:
+
+- `ValueType` is not `basic_json`,
+- `json_serializer<ValueType>` has a `from_json()` method of the form `void from_json(const basic_json&, ValueType&)`
+
+## Template parameters
+
+`ValueType`
+:   the value type to return
+
+## Return value
+
+the input parameter, allowing chaining calls
+
+## Exceptions
+
+Depends on what `json_serializer<ValueType>` `from_json()` method throws
+
+## Example
+
+??? example
+
+    The example below shows several conversions from JSON values to other types. There a few things to note: (1)
+    Floating-point numbers can be converted to integers, (2) A JSON array can be converted to a standard
+    `#!cpp std::vector<short>`, (3) A JSON object can be converted to C++ associative containers such as
+    `#cpp std::unordered_map<std::string, json>`.
+        
+    ```cpp
+    --8<-- "examples/get_to.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/get_to.output"
+    ```
+
+## Version history
+
+- Since version 3.3.0.

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

@@ -33,14 +33,14 @@ class basic_json;
 | -------------------- | ----------- | ------------ |
 | `ObjectType`         | type for JSON objects | [`object_t`](object_t.md) |
 | `ArrayType`          | type for JSON arrays | [`array_t`](array_t.md) |
-| `StringType`         | type for JSON strings and object keys | `string_t` |
+| `StringType`         | type for JSON strings and object keys | [`string_t`](string_t.md) |
-| `BooleanType`        | type for JSON booleans | `boolean_t` |
+| `BooleanType`        | type for JSON booleans | [`boolean_t`](boolean_t.md) |
 | `NumberIntegerType`  | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) |
 | `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) |
 | `NumberFloatType`    | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) |
 | `AllocatorType`      | type of the allocator to use | |
-| `JSONSerializer`     | the serializer to resolve internal calls to `to_json()` and `from_json()` | |
+| `JSONSerializer`     | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) |
-| `BinaryType`         | type for binary arrays | `binary_t` |
+| `BinaryType`         | type for binary arrays | [`binary_t`](binary_t.md) |
 
 ## Iterator invalidation
 
@@ -48,9 +48,10 @@ Todo
 
 ## Member types
 
+- [**adl_serializer**](../adl_serializer.md) - the default serializer
 - [**value_t**](value_t.md) - the JSON type enumeration
 - [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
-- json_serializer
+- [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON
 - [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
 - [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
 - initializer_list_t
@@ -136,7 +137,7 @@ Functions to inspect the type of a JSON value.
 Direct access to the stored value of a JSON value.
 
 - [**get**](get.md) - get a value
-- get_to - get a value
+- [**get_to**](get_to.md) - get a value and write it to a destination
 - [**get_ptr**](get_ptr.md) - get a pointer value
 - [**get_ref**](get_ref.md) - get a reference value
 - [**operator ValueType**](operator_ValueType.md) - get a value

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

@@ -0,0 +1,24 @@
+# basic_json::json_serializer
+
+```cpp
+template<typename T, typename SFINAE>
+using json_serializer = JSONSerializer<T, SFINAE>;
+```
+
+## Template parameters
+
+`T`
+:   type to convert; will be used in the `to_json`/`from_json` functions
+
+`SFINAE`
+:   type to add compile type checks via SFINAE; usually `#!cpp void`
+
+## Notes
+
+#### Default type
+
+The default values for `json_serializer` is [`adl_serializer`](../adl_serializer.md).
+
+## Version history
+
+- Since version 2.0.0.

doc/mkdocs/mkdocs.yml

@@ -112,6 +112,7 @@ nav:
         - api/basic_json/get_binary.md
         - api/basic_json/get_ptr.md
         - api/basic_json/get_ref.md
+        - api/basic_json/get_to.md
         - api/basic_json/input_format_t.md
         - api/basic_json/insert.md
         - api/basic_json/invalid_iterator.md
@@ -129,6 +130,7 @@ nav:
         - api/basic_json/is_string.md
         - api/basic_json/is_structured.md
         - api/basic_json/items.md
+        - api/basic_json/json_serializer.md
         - api/basic_json/max_size.md
         - api/basic_json/meta.md
         - api/basic_json/merge_patch.md
@@ -171,6 +173,7 @@ nav:
         - api/basic_json/update.md
         - api/basic_json/value.md
         - api/basic_json/value_t.md
+      - api/adl_serializer.md
       - api/json.md
       - api/json_pointer.md
       - api/ordered_map.md