📝 update documentation (#4723)

Signed-off-by: Niels Lohmann <[email protected]>

Author: nlohmann

README.md

@@ -1706,6 +1706,44 @@ I deeply appreciate the help of the following people.
 344. [Aleksei Sapitskii](https://github.com/aleksproger) added support for Apple's Swift Package Manager.
 345. [Benjamin Buch](https://github.com/bebuch) fixed the installation path in CMake.
 346. [Colby Haskell](https://github.com/colbychaskell) clarified the parse error message in case a file cannot be opened.
+347. [Juan Carlos Arevalo Baeza](https://github.com/TheJCAB) fixed the enum conversion.
+348. [alferov](https://github.com/ALF-ONE) fixed a version in the documentation.
+349. [ss](https://github.com/serge-s) fixed the amalgamation call.
+350. [AniketDhemare](https://github.com/AniketDhemare) fixed a version in the documentation.
+351. [Philip Müller](https://github.com/philip-paul-mueller) fixed an example.
+352. [Leila Shcheglova](https://github.com/LeilaShcheglova) fixed a warning in a test.
+353. [Alex Prabhat Bara](https://github.com/alexprabhat99) fixed a function name in the documentation.
+354. [laterlaugh](https://github.com/laterlaugh) fixed some typos.
+355. [Yuanhao Jia](https://github.com/MrJia1997) fixed the GDB pretty printer.
+356. [Fallen_Breath](https://github.com/Fallen-Breath) fixed an example for JSON Pointer.
+357. [Nikhil Idiculla](https://github.com/tsnl) fixed some typos.
+358. [Griffin Myers](https://github.com/gmyers18) updated the Natvis file.
+359. [thetimr](https://github.com/thetimr) fixed a typo in the documentation.
+360. [Balazs Erseki](https://github.com/zerocukor287) fixed a URL in the contribution guidelines.
+361. [Niccolò Iardella](https://github.com/rotolof) added `NLOHMANN_DEFINE_DERIVED_TYPE_*` macros.
+362. [Borislav Stanimirov](https://github.com/iboB) allowed overriding the CMake target name.
+363. [Captain Crutches](https://github.com/captaincrutches) made `iterator_proxy_value` a `std::forward_iterator`.
+364. [Fredrik Sandhei](https://github.com/fsandhei) added type conversion support for `std::optional`.
+365. [jh96](https://github.com/jordan-hoang) added exceptions when `nullptr` is passed to `parse`.
+366. [Stuart Gorman](https://github.com/StuartGorman) fixed number parsing when `EINTR` set in `errno`.
+367. [Dylan Baker](https://github.com/dcbaker) generated a pkg-config file that follows the pkg-config conventions.
+368. [Tianyi Chen](https://github.com/TianyiChen) optimized the binary `get_number` implementation.
+369. [peng-wang-cn](https://github.com/peng-wang-cn) added type conversion support for multidimensional arrays.
+370. [Einars Netlis-Galejs](https://github.com/EinarsNG) added `ONLY_SERIALIZE` for `NLOHMANN_DEFINE_DERIVED_TYPE_*` macros.
+371. [Marcel](https://github.com/mering) removed `alwayslink=True` Bazel flag.
+372. [Harinath Nampally](https://github.com/hnampally) added diagnostic positions to exceptions.
+373. [Nissim Armand Ben Danan](https://github.com/NissimBendanan) fixed `NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT` with an empty JSON instance.
+374. [Michael Valladolid](https://github.com/codenut) added support for BSON uint64 serialization/deserialization.
+375. [Nikhil](https://github.com/nikhilreddydev) updated the documentation.
+376. [Nebojša Cvetković](https://github.com/nebkat) added support for BJDATA optimized binary array type.
+377. [Sushrut Shringarputale](https://github.com/sushshring) added support for diagnostic positions. 
+378. [kimci86](https://github.com/kimci86) templated to `NLOHMANN_DEFINE_TYPE` macros to also support `ordered_json`.
+379. [Richard Topchii](https://github.com/richardtop) added support for VisionOS in the Swift Package Manager.
+380. [Robert Chisholm](https://github.com/Robadob) fixed a typo.
+381. [zjyhjqs](https://github.com/zjyhjqs) added CPack support.
+382. [bitFiedler](https://github.com/bitFiedler) made GDB pretty printer work with Python 3.8.
+383. [Gianfranco Costamagna](https://github.com/LocutusOfBorg) fixed a compiler warning.
+384. [risa2000](https://github.com/risa2000) made `std::filesystem::path` conversion to/from UTF-8 encoded string explicit.
 
 Thanks a lot for helping out! Please [let me know](mailto:[email protected]) if I forgot someone.
 

docs/mkdocs/docs/api/basic_json/accept.md

@@ -17,8 +17,8 @@ Checks whether the input is valid JSON.
 1. Reads from a compatible input.
 2. Reads from a pair of character iterators
     
-    The value_type of the iterator must be an integral type with size of 1, 2 or 4 bytes, which will be interpreted
-    respectively as UTF-8, UTF-16 and UTF-32.
+    The value_type of the iterator must be an integral type with a size of 1, 2, or 4 bytes, which will be interpreted
+    respectively as UTF-8, UTF-16, and UTF-32.
     
 Unlike the [`parse()`](parse.md) function, this function neither throws an exception in case of invalid JSON input
 (i.e., a parse error) nor creates diagnostic information.
@@ -51,10 +51,10 @@ Unlike the [`parse()`](parse.md) function, this function neither throws an excep
     (`#!cpp false`); (optional, `#!cpp false` by default)
 
 `first` (in)
-:   iterator to start of character range
+:   iterator to the start of the character range
 
 `last` (in)
-:   iterator to end of character range
+:   iterator to the end of the character range
 
 ## Return value
 
@@ -101,7 +101,7 @@ A UTF-8 byte order mark is silently ignored.
 
 - Added in version 3.0.0.
 - Ignoring comments via `ignore_comments` added in version 3.9.0.
-- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.11.4.
+- Changed [runtime assertion](../../features/assertions.md) in case of `FILE*` null pointers to exception in version 3.12.0.
 
 !!! warning "Deprecation"
 

docs/mkdocs/docs/api/basic_json/at.md

@@ -59,29 +59,29 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 1. The function can throw the following exceptions:
     - Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an array;
-      in this case, calling `at` with an index makes no sense. See example below.
+      in this case, calling `at` with an index makes no sense. See the example below.
     - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if the index `idx` is out of
-      range of the array; that is, `idx >= size()`. See example below.
+      range of the array; that is, `idx >= size()`. See the example below.
 2. The function can throw the following exceptions:
     - Throws [`type_error.304`](../../home/exceptions.md#jsonexceptiontype_error304) if the JSON value is not an object;
-      in this case, calling `at` with a key makes no sense. See example below.
+      in this case, calling `at` with a key makes no sense. See the example below.
     - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the key `key` is not
-      stored in the object; that is, `find(key) == end()`. See example below.
+      stored in the object; that is, `find(key) == end()`. See the example below.
 3. See 2.
 4. The function can throw the following exceptions:
     - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed
-      JSON pointer `ptr` begins with '0'. See example below.
+      JSON pointer `ptr` begins with '0'. See the example below.
     - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed
-      JSON pointer `ptr` is not a number. See example below.
+      JSON pointer `ptr` is not a number. See the example below.
     - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index in the passed
-      JSON pointer `ptr` is out of range. See example below.
+      JSON pointer `ptr` is out of range. See the example below.
     - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used
       in the passed JSON pointer `ptr`. As `at` provides checked access (and no elements are implicitly inserted), the
-      index '-' is always invalid. See example below.
+      index '-' is always invalid. See the example below.
     - Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if the JSON pointer describes a
-      key of an object which cannot be found. See example below.
+      key of an object which cannot be found. See the example below.
     - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can
-      not be resolved. See example below.
+      not be resolved. See the example below.
 
 ## Complexity
 

docs/mkdocs/docs/api/basic_json/back.md

@@ -17,8 +17,8 @@ return *tmp;
 
 ## Return value
 
-In case of a structured type (array or object), a reference to the last element is returned. In case of number, string,
-boolean, or binary values, a reference to the value is returned.
+In the case of a structured type (array or object), a reference to the last element is returned. In the case of number,
+string, boolean, or binary values, a reference to the value is returned.
 
 ## Exception safety
 

docs/mkdocs/docs/api/basic_json/basic_json.md

@@ -99,8 +99,8 @@ basic_json(basic_json&& other) noexcept;
     2. C++ has no way of describing mapped types other than to list a list of pairs. As JSON requires that keys must be
        of type string, rule 2 is the weakest constraint one can pose on initializer lists to interpret them as an
        object.
-    3. In all other cases, the initializer list could not be interpreted as JSON object type, so interpreting it as JSON
-       array type is safe.
+    3. In all other cases, the initializer list could not be interpreted as a JSON object type, so interpreting it as a
+       JSON array type is safe.
     
     With the rules described above, the following JSON values cannot be expressed by an initializer list:
     
@@ -113,7 +113,7 @@ basic_json(basic_json&& other) noexcept;
 6. Constructs a JSON array value by creating `cnt` copies of a passed value. In case `cnt` is `0`, an empty array is
    created.
 
-7. Constructs the JSON value with the contents of the range `[first, last)`. The semantics depends on the different
+7. Constructs the JSON value with the contents of the range `[first, last)`. The semantics depend on the different
    types a JSON value can have:
 
     - In case of a `#!json null` type, [invalid_iterator.206](../../home/exceptions.md#jsonexceptioninvalid_iterator206)
@@ -175,10 +175,10 @@ basic_json(basic_json&& other) noexcept;
 :   the number of JSON copies of `val` to create
 
 `first` (in)
-:   begin of the range to copy from (included)
+:   the beginning of the range to copy from (included)
 
 `last` (in)
-:   end of the range to copy from (excluded)
+:   the end of the range to copy from (excluded)
 
 `other` (in)
 :   the JSON value to copy/move
@@ -188,10 +188,10 @@ basic_json(basic_json&& other) noexcept;
 1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
 2. No-throw guarantee: this constructor never throws exceptions.
 3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
-   `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
+   `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
    JSON value.
 4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no
-   `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any
+   `to_json()` function was provided), a strong guarantee holds: if an exception is thrown, there are no changes to any
    JSON value.
 5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
 6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
@@ -217,7 +217,7 @@ basic_json(basic_json&& other) noexcept;
       `[first, last)` is undefined.
     - Throws [`invalid_iterator.204`](../../home/exceptions.md#jsonexceptioninvalid_iterator204) if iterators `first`
       and `last` belong to a primitive type (number, boolean, or string), but `first` does not point to the first
-      element anymore. In this case, the range `[first, last)` is undefined. See example code below.
+      element anymore. In this case, the range `[first, last)` is undefined. See the example code below.
     - Throws [`invalid_iterator.206`](../../home/exceptions.md#jsonexceptioninvalid_iterator206) if iterators `first`
       and `last` belong to a `#!json null` value. In this case, the range `[first, last)` is undefined.
 8. (none)
@@ -333,7 +333,7 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__list_init_t.output"
     ```
 
-??? example "Example: (6) construct an array with count copies of given value"
+??? example "Example: (6) construct an array with count copies of a given value"
 
     The following code shows examples for creating arrays with several copies of a given value.
      

docs/mkdocs/docs/api/basic_json/binary.md

@@ -21,7 +21,7 @@ create a value for serialization to those formats.
 ## Parameters
 
 `init` (in)
-:   container containing bytes to use as binary type
+:   container containing bytes to use as a binary type
 
 `subtype` (in)
 :   subtype to use in CBOR, MessagePack, and BSON
@@ -42,8 +42,8 @@ Linear in the size of `init`; constant for `typename binary_t::container_type&&
 
 Note, this function exists because of the difficulty in correctly specifying the correct template overload in the
 standard value ctor, as both JSON arrays and JSON binary arrays are backed with some form of a `std::vector`. Because
-JSON binary arrays are a non-standard extension it was decided that it would be best to prevent automatic initialization
-of a binary array type, for backwards compatibility and so it does not happen on accident.
+JSON binary arrays are a non-standard extension, it was decided that it would be best to prevent automatic
+initialization of a binary array type, for backwards compatibility and so it does not happen on accident.
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/binary_t.md

@@ -56,11 +56,11 @@ type `#!cpp binary_t*` must be dereferenced.
 - MessagePack
     - If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
       fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
-      then added as signed 8-bit integer.
+      then added as a signed 8-bit integer.
     - If no subtype is given, the bin family (bin8, bin16, bin32) is used.
 
 - BSON
-    - If a subtype is given, it is used and added as unsigned 8-bit integer.
+    - If a subtype is given, it is used and added as an unsigned 8-bit integer.
     - If no subtype is given, the generic binary subtype 0x00 is used.
 
 ## Examples
@@ -86,4 +86,4 @@ type `#!cpp binary_t*` must be dereferenced.
 
 ## Version history
 
-- Added in version 3.8.0. Changed type of subtype to `std::uint64_t` in version 3.10.0.
+- Added in version 3.8.0. Changed the type of subtype to `std::uint64_t` in version 3.10.0.

docs/mkdocs/docs/api/basic_json/clear.md

@@ -33,7 +33,7 @@ Linear in the size of the JSON value.
 
 ## Notes
 
-All iterators, pointers and references related to this container are invalidated.
+All iterators, pointers, and references related to this container are invalidated.
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/contains.md

@@ -35,7 +35,7 @@ bool contains(const json_pointer& ptr) const;
 
 ## Return value
 
-1. `#!cpp true` if an element with specified `key` exists. If no such element with such key is found or the JSON value
+1. `#!cpp true` if an element with specified `key` exists. If no such element with such a key is found or the JSON value
    is not an object, `#!cpp false` is returned.
 2. See 1.
 3. `#!cpp true` if the JSON pointer can be resolved to a stored value, `#!cpp false` otherwise.

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

@@ -8,7 +8,7 @@ string_t dump(const int indent = -1,
 ```
 
 Serialization function for JSON values. The function tries to mimic Python's
-[`json.dumps()` function](https://docs.python.org/2/library/json.html#json.dump), and currently  supports its `indent`
+[`json.dumps()` function](https://docs.python.org/2/library/json.html#json.dump), and currently supports its `indent`
 and `ensure_ascii` parameters.
     
 ## Parameters
@@ -49,7 +49,7 @@ Linear.
 
 ## Notes
 
-Binary values are serialized as object containing two keys:
+Binary values are serialized as an object containing two keys:
 
 - "bytes": an array of bytes as integers
 - "subtype": the subtype as integer or `#!json null` if the binary has no subtype