docs: clarify document inputs, decoding, get<T>() and editing

Address review comments: say which inputs are borrowed and that a wide
string pointer is an extra input, which values are decoded during parsing,
that get<T>() reads only built-in types directly, all forms of set() and
that the document's insert() is array-only, and how to store wide strings.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/api/basic_json_document/index.md

@@ -118,7 +118,7 @@ points apply to every edit:
 ## See also
 
 - [basic_json_view](../basic_json_view/index.md) - the read-only handle to a value of a document
-- [json_document](../json_document.md) - the document type of the default specialization
+- [json_document](../json_document.md) - this template for the default specialization `nlohmann::json`
 - [Zero-copy JSON views](../../features/json_view.md) - the concept behind documents and views
 
 ## Version history

docs/mkdocs/docs/api/basic_json_document/parse.md

@@ -21,10 +21,11 @@ static basic_json_document parse(IteratorType first, IteratorType last,
 
 Both overloads accept the same JSON text as [`BasicJsonType::parse()`](../basic_json/parse.md), with the same
 `ignore_comments`/`ignore_trailing_commas` options, but build a [`basic_json_document`](index.md) (a flat index into
-the input) instead of a tree of `BasicJsonType` values. They take the same inputs as `BasicJsonType::parse()`, plus a
-pointer to a null-terminated wide string, which `BasicJsonType::parse()` does not accept. Byte inputs that stay alive
-can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, non-contiguous iterators) are read into a copy
-that the document owns -- see the Notes. Use [`parse_copy()`](parse_copy.md) to get an owned copy of a borrowable input
+the input) instead of a tree of `BasicJsonType` values. They take every input `BasicJsonType::parse()` takes, and in
+addition a pointer to a null-terminated wide string (which `BasicJsonType::parse()` rejects). Contiguous inputs of
+single-byte characters that stay alive can be borrowed; all others (streams, `#!cpp FILE*`, wide characters, which
+must be converted to UTF-8, and non-contiguous iterators) are read into a copy that the document owns -- see the
+Notes. Use [`parse_copy()`](parse_copy.md) to get an owned copy of a borrowable input
 as well.
 
 ## Template parameters

docs/mkdocs/docs/features/conversions.md

@@ -40,8 +40,10 @@ which avoids repeating it:
 
 !!! info "Getting values out of a document or a view"
 
-    A [view](../api/basic_json_view/index.md) offers the same `get<T>()` conversion, but reads it straight from the
-    document's index, without building a `basic_json` value first. Two conversions never copy at all:
+    A [view](../api/basic_json_view/index.md) offers the same `get<T>()` conversion. For the built-in types (booleans,
+    numbers, strings, `#!cpp std::vector`, `#!cpp std::map`, ...) it reads the value straight from the document's
+    index, without building a `basic_json` value first; user-defined types with a `from_json()` are converted from a
+    `basic_json` value, see the [list](../api/basic_json_view/get.md). Two conversions never copy at all:
     [`get_string()`](../api/basic_json_view/get_string.md) returns a string as a view into the source text, and
     [`number_token()`](../api/basic_json_view/number_token.md) returns a number exactly as it was written. Every other
     type is obtained from a subtree that is built on demand with

docs/mkdocs/docs/features/modifying_values.md

@@ -89,10 +89,12 @@ a.erase(1);             // [1,3,4]  (erase by index)
 
 The operations above work on a `basic_json` value. A JSON text that was parsed into a
 [document](json_view.md#editing-a-document) can also be changed in place, without building a `basic_json` tree for the
-parts that are not touched: [`set`](../api/basic_json_document/set.md) replaces a value or an object member,
+parts that are not touched: [`set`](../api/basic_json_document/set.md) replaces a value, adds or replaces an object
+member, or replaces an array element (also through a JSON pointer),
 [`push_back`](../api/basic_json_document/push_back.md) appends to an array,
-[`insert`](../api/basic_json_document/insert.md) inserts into an array, and
-[`erase`](../api/basic_json_document/erase.md) removes a member or an element. These functions are available on the
+[`insert`](../api/basic_json_document/insert.md) inserts into an array (unlike `basic_json::insert`, it has no object
+overload; members are added with `set`), and [`erase`](../api/basic_json_document/erase.md) removes a member or an
+element. These functions are available on the
 editable document types, such as [`json_editable_document`](../api/json_editable_document.md).
 
 ## See also

docs/mkdocs/docs/features/parsing/index.md

@@ -110,8 +110,10 @@ You can influence a DOM parse without switching to the SAX interface by passing
 A third model sits between DOM and SAX: [`basic_json_document::parse`](../../api/basic_json_document/parse.md) parses
 the input into a document that keeps the text and a flat index of the values in it, and
 [`basic_json_view`](../../api/basic_json_view/index.md) gives read-only access to the values through that index.
-Strings and numbers stay in the source text and are only decoded when they are read, which is faster and uses less
-memory than building a tree of `basic_json` values when only parts of the document are needed. A document can also be
+The whole input is validated during parsing, but only strings that contain escape sequences are decoded right away
+(into a buffer owned by the document). Numbers and all other strings stay in the source text and are only converted
+when they are read, which is faster and uses less memory than building a tree of `basic_json` values when only parts
+of the document are needed. A document can also be
 modified in place, and it can be saved and loaded again without parsing it.
 
 ```cpp

docs/mkdocs/docs/home/faq.md

@@ -147,7 +147,7 @@ json::parse(std::string("\"") + '\0' + "\""); // throws parse_error.101: control
 
     Why are wide strings (e.g., `std::wstring`) dumped as arrays of numbers?
 
-As described [above](#parse-errors-reading-non-ascii-characters), the library stores its strings as UTF-8. To store a wide string, you need to change the encoding.
+As described [above](#parse-errors-reading-non-ascii-characters), the library stores its strings as UTF-8. To store a wide string as a string, convert it to a UTF-8 encoded `std::string` first, as in the example below.
 
 !!! example