📝 add more documentation

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

@@ -57,16 +57,18 @@ Binary values are serialized as object containing two keys:
 
 ## Example
 
-The following example shows the effect of different `indent`,
+??? example
+
+    The following example shows the effect of different `indent`,
     `indent_char`, and `ensure_ascii` parameters to the result of the
     serialization.
 
-```cpp
---8<-- "examples/dump.cpp"
-```
-
-Output:
-
-```json
---8<-- "examples/dump.output"
-```
+    ```cpp
+    --8<-- "examples/dump.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/dump.output"
+    ```

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

@@ -1,15 +1,253 @@
-# Overview
+# basic_json
 
 !!! note
     
     This page is under construction.
 
+Defined in header `<json.hpp>`
+
+```cpp
+template<template<typename, typename, typename...> class ObjectType,  
+         template<typename, typename...> class ArrayType,             
+         class StringType, class BooleanType, class NumberIntegerType,
+         class NumberUnsignedType, class NumberFloatType,             
+         template<typename> class AllocatorType,                      
+         template<typename, typename = void> class JSONSerializer,    
+         class BinaryType>
+class basic_json
+```
+
+## Specializations
+
+- json
+- ordered_json
+
+## Template parameters
+
+- ObjectType
+- ArrayType
+- StringType
+- BooleanType
+- NumberIntegerType
+- NumberUnsignedType
+- NumberFloatType
+- AllocatorType
+- JSONSerializer
+- BinaryType
+
+## Iterator invalidation
+
+## Member types
+
+- value_t
+- json_pointer
+- json_serializer
+- error_handler_t
+- cbor_tag_handler_t
+- initializer_list_t
+- input_format_t
+- json_sax_t
+
+### Exceptions
+
+- exception
+- parse_error
+- invalid_iterator
+- type_error
+- out_of_range
+- other_error
+
+### Container types
+
+- value_type
+- reference
+- const_reference
+- difference_type
+- size_type
+- allocator_type
+- pointer
+- const_pointer
+- iterator
+- const_iterator
+- reverse_iterator
+- const_reverse_iterator
+
+### JSON value data types
+
+- object_comparator_t
+- object_t
+- array_t
+- string_t
+- boolean_t
+- number_integer_t
+- number_unsigned_t
+- number_float_t
+- binary_t
+
+### Parser callback
+
+- parse_event_t
+- parser_callback_t
+
 ## Member functions
 
+- (constructor)
+- (destructor)
+- binary (static) - explicitly create a binary array
+- array (static) - explicitly create an array
+- object (static) - explicitly create an object
+- operator= - copy assignment
+
 ### Object inspection
 
-- [dump](dump.md) - serialization
+Functions to inspect the type of a JSON value.
+
+- type - return the type of the JSON value
+- is_primitive - return whether type is primitive
+- is_structured - return whether type is structured
+- is_null - return whether value is null
+- is_boolean - return whether value is a boolean
+- is_number - return whether value is a number
+- is_number_integer - return whether value is an integer number
+- is_number_unsigned - return whether value is an unsigned integer number
+- is_number_float - return whether value is a floating-point number
+- is_object - return whether value is an object
+- is_array - return whether value is an array
+- is_string - return whether value is a string
+- is_binary - return whether value is a binary array
+- is_discarded - return whether value is discarded
+- operator value_t - return the type of the JSON value
+
+### Value access
+
+Direct access to the stored value of a JSON value.
+
+- get - get a value
+- get_to - get a value
+- get_ptr - get a pointer value
+- get_ref - get a reference value
+- operator ValueType - get a value
+- get_binary - get a binary value
+
+### Element access
+
+Access to the JSON value
+
+- at - access specified array element with bounds checking
+- at - access specified object element with bounds checking
+- operator[] - access specified array element
+- operator[] - access specified object element
+- value - access specified object element with default value
+- front - access the first element
+- back - access the last element
+- erase - remove elements
+
+### Lookup
+
+- find - find an element in a JSON object
+- count - returns the number of occurrences of a key in a JSON object
+- contains - check the existence of an element in a JSON object
+
+### Iterators
+
+- begin - returns an iterator to the first element
+- cbegin - returns a const iterator to the first element
+- end - returns an iterator to one past the last element
+- cend - returns a const iterator to one past the last element
+- rbegin - returns an iterator to the reverse-beginning
+- rend - returns an iterator to the reverse-end
+- crbegin - returns a const iterator to the reverse-beginning
+- crend - returns a const iterator to the reverse-end
+- items - wrapper to access iterator member functions in range-based for
+
+### Capacity
+
+- empty - checks whether the container is empty
+- size - returns the number of elements
+- max_size - returns the maximum possible number of elements
+
+### Modifiers
+
+- clear - clears the contents
+- push_back - add an object to an array
+- operator+= - add an object to an array
+- push_back - add an object to an object
+- operator+= - add an object to an object
+- emplace_back - add an object to an array
+- emplace - add an object to an object if key does not exist
+- insert - inserts element
+- update - updates a JSON object from another object, overwriting existing keys 
+- swap - exchanges the values
+
+### Lexicographical comparison operators
+
+- operator== - comparison: equal
+- operator!= - comparison: not equal
+- operator< - comparison: less than
+- operator<= - comparison: less than or equal
+- operator> - comparison: greater than
+- operator>= - comparison: greater than or equal
+
+### Serialization
+
+- [**dump**](dump.md) - serialization
+- to_string - user-defined to_string function for JSON values
+
+### Deserialization
+
+- [**parse**](parse.md) - deserialize from a compatible input
+- accept - check if the input is valid JSON
+- sax_parse - generate SAX events
+
+### Convenience functions
+
+- type_name - return the type as string
+
+### JSON Pointer functions
+
+- at - access specified object element with bounds checking via JSON Pointer
+- operator[] - access specified element via JSON Pointer
+- value - access specified object element with default value via JSON Pointer
+- flatten - return flattened JSON value
+- unflatten - unflatten a previously flattened JSON value
+
+### JSON Patch functions
+
+- patch - applies a JSON patch
+- diff (static) - creates a diff as a JSON patch
+
+### JSON Merge Patch functions
+
+- merge_patch - applies a JSON Merge Patch
 
 ## Static functions
 
-- [meta](meta.md) - returns version information on the library
+- [**meta**](meta.md) - returns version information on the library
+- get_allocator - returns the allocator associated with the container
+
+### Binary formats
+
+- to_cbor - create a CBOR serialization of a given JSON value
+- to_msgpack - create a MessagePack serialization of a given JSON value
+- to_ubjson - create a UBJSON serialization of a given JSON value
+- to_bson - create a BSON serialization of a given JSON value
+- from_cbor - create a JSON value from an input in CBOR format
+- from_msgpack - create a JSON value from an input in MessagePack format
+- from_ubjson - create a JSON value from an input in UBJSON format
+- from_bson - create a JSON value from an input in BSON format
+
+## Non-member functions
+
+- operator<<(std::ostream&) - serialize to stream
+- operator>>(std::istream&) - deserialize from stream
+
+## Literals
+
+- operator""_json
+- operator""_json_pointer
+
+## Helper classes
+
+- std::hash<nlohmann::json\>
+- std::less<nlohmann::value_t\>
+- std::swap<nlohmann::json\>

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

@@ -0,0 +1,146 @@
+# basic_json::parse
+
+```cpp
+// (1)
+template<typename InputType>
+static basic_json parse(InputType&& i,
+                        const parser_callback_t cb = nullptr,
+                        const bool allow_exceptions = true,
+                        const bool ignore_comments = false)
+
+// (2)
+template<typename IteratorType>
+static basic_json parse(IteratorType first,
+                        IteratorType last,
+                        const parser_callback_t cb = nullptr,
+                        const bool allow_exceptions = true,
+                        const bool ignore_comments = false)
+```
+
+1. Deserialize from a compatible input.
+2. Deserialize from a pair of character iterators
+    
+    The value_type of the iterator must be a integral type with size of 1, 2 or
+    4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32.
+
+## Template parameters
+
+`InputType`
+:   A compatible input, for instance:
+    
+    - an `std::istream` object
+    - a `FILE` pointer
+    - a C-style array of characters
+    - a pointer to a null-terminated string of single byte characters
+    - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of
+      iterators.
+
+`IteratorType`
+:   Description
+
+## Parameters
+
+`i` (in)
+:   Input to parse from.
+
+`cb` (in)
+:   a parser callback function of type `parser_callback_t`
+    which is used to control the deserialization by filtering unwanted values
+    (optional)
+
+`allow_exceptions` (in)
+:    whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
+
+`ignore_comments` (in)
+:   whether comments should be ignored and treated
+    like whitespace (`#!cpp true`) or yield a parse error (`#!cpp false`); (optional, `#!cpp false` by
+    default)
+
+`first` (in)
+:   iterator to start of character range
+
+`last` (in)
+:   iterator to end of character range
+
+## Return value
+
+Deserialized JSON value; in case of a parse error and `allow_exceptions`
+set to `#!cpp false`, the return value will be `value_t::discarded`.
+
+## Exception safety
+
+## Complexity
+
+Linear in the length of the input. The parser is a predictive
+LL(1) parser. The complexity can be higher if the parser callback function
+`cb` or reading from (1) the input `i` or (2) the iterator range [`first`, `last`] has a super-linear complexity.
+
+## Notes
+
+(1) A UTF-8 byte order mark is silently ignored.
+
+## Examples
+
+??? example
+
+    The example below demonstrates the `parse()` function reading
+    from an array.
+
+    ```cpp
+    --8<-- "examples/parse__array__parser_callback_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse__array__parser_callback_t.output"
+    ```
+
+??? example
+
+    The example below demonstrates the `parse()` function with
+    and without callback function.
+
+    ```cpp
+    --8<-- "examples/parse__string__parser_callback_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse__string__parser_callback_t.output"
+    ```
+
+??? example
+
+    The example below demonstrates the `parse()` function with
+    and without callback function.
+
+    ```cpp
+    --8<-- "examples/parse__istream__parser_callback_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse__istream__parser_callback_t.output"
+    ```
+
+??? example
+
+    The example below demonstrates the `parse()` function reading
+    from a contiguous container.
+
+    ```cpp
+    --8<-- "examples/parse__contiguouscontainer__parser_callback_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
+    ```
+
+## History
+
+(1) version 2.0.3 (contiguous containers); version 3.9.0 allowed to ignore comments.

doc/mkdocs/docs/hooks.py

@@ -3,5 +3,8 @@ import os.path
 
 
 def copy_doxygen(*args, **kwargs):
-    shutil.copytree('../html', os.path.join(kwargs['config']['site_dir'], 'doxygen'))
-    print('Copy Doxygen complete')
+    doxygen_dir = os.path.join(kwargs['config']['site_dir'], 'doxygen')
+    if not os.path.isdir(doxygen_dir) or not os.listdir(doxygen_dir):
+        print('Copy Doxygen files...')
+        shutil.copytree('../html', doxygen_dir)
+        print('Copy Doxygen complete')

doc/mkdocs/mkdocs.yml

@@ -74,6 +74,7 @@ nav:
         - api/basic_json/index.md
         - api/basic_json/dump.md
         - api/basic_json/meta.md
+        - api/basic_json/parse.md
 
 # Extras
 extra: