Overwork documentation (#4516)

.github/workflows/publish_documentation.yml

@@ -25,9 +25,6 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Install and update PlantUML
-        run: sudo apt-get update ; sudo apt-get install -y plantuml
-
       - name: Install virtual environment
         run: make install_venv -C docs/mkdocs
 

CMakeLists.txt

@@ -81,23 +81,23 @@ else()
 endif()
 
 if (NOT JSON_ImplicitConversions)
-    message(STATUS "Implicit conversions are disabled")
+    message(STATUS "Implicit conversions are disabled (JSON_USE_IMPLICIT_CONVERSIONS=0)")
 endif()
 
 if (JSON_DisableEnumSerialization)
-    message(STATUS "Enum integer serialization is disabled")
+    message(STATUS "Enum integer serialization is disabled (JSON_DISABLE_ENUM_SERIALIZATION=0)")
 endif()
 
 if (JSON_LegacyDiscardedValueComparison)
-    message(STATUS "Legacy discarded value comparison enabled")
+    message(STATUS "Legacy discarded value comparison enabled (JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON=1)")
 endif()
 
 if (JSON_Diagnostics)
-    message(STATUS "Diagnostics enabled")
+    message(STATUS "Diagnostics enabled (JSON_DIAGNOSTICS=1)")
 endif()
 
 if (NOT JSON_GlobalUDLs)
-    message(STATUS "User-defined string literals are not put in the global namespace")
+    message(STATUS "User-defined string literals are not put in the global namespace (JSON_USE_GLOBAL_UDLS=0)")
 endif()
 
 if (JSON_SystemInclude)

README.md

@@ -39,6 +39,7 @@
   - [Conversions to/from arbitrary types](#arbitrary-types-conversions)
   - [Specializing enum conversion](#specializing-enum-conversion)
   - [Binary formats (BSON, CBOR, MessagePack, UBJSON, and BJData)](#binary-formats-bson-cbor-messagepack-ubjson-and-bjdata)
+- [Customers](#customers)
 - [Supported compilers](#supported-compilers)
 - [Integration](#integration)
   - [CMake](#cmake)
@@ -1112,6 +1113,11 @@ binary.set_subtype(0x10);
 auto cbor = json::to_msgpack(j); // 0xD5 (fixext2), 0x10, 0xCA, 0xFE
 ```
 
+## Customers
+
+The library is used in multiple projects, applications, operating systems, etc. The list below is not exhaustive, but the result of an internet search. If you know further customers of the library, please let me know, see [contact](#contact).
+
+[![](docs/mkdocs/docs/images/customers.png)](https://json.nlohmann.me/home/customers/)
 
 ## Supported compilers
 

cmake/ci.cmake

@@ -1024,8 +1024,8 @@ add_custom_target(ci_test_examples
 )
 
 add_custom_target(ci_test_api_documentation
-    COMMAND ${Python3_EXECUTABLE} scripts/check_structure.py
-    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs
+    COMMAND ${Python3_EXECUTABLE} ../scripts/check_structure.py
+    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs/mkdocs/docs
     COMMENT "Lint the API documentation"
 )
 

docs/mkdocs/Makefile

@@ -35,3 +35,11 @@ install_venv: requirements.txt
 # uninstall the virtual environment
 uninstall_venv: clean
 	rm -fr venv
+
+update_requirements:
+	rm -fr venv_small
+	python3 -mvenv venv_small
+	venv_small/bin/pip3 install pur
+	venv_small/bin/pur -r requirements.txt
+	rm -fr venv_small venv
+	make install_venv

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

@@ -29,9 +29,9 @@ Unlike the [`parse`](parse.md) function, this function neither throws an excepti
 :   A compatible input, for instance:
     
     - an `std::istream` object
-    - a `FILE` pointer (must not be null)
+    - a `FILE` pointer (throws if null)
     - a C-style array of characters
-    - a pointer to a null-terminated string of single byte characters
+    - a pointer to a null-terminated string of single byte characters (throws if null)
     - a `std::string`
     - an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of iterators.
 
@@ -64,18 +64,17 @@ Whether the input is valid JSON.
 
 Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
 
+## Exceptions
+
+Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an empty input like a null `FILE*` or `char*` pointer.
+
 ## Complexity
 
 Linear in the length of the input. The parser is a predictive LL(1) parser.
 
 ## Notes
 
-(1) A UTF-8 byte order mark is silently ignored.
-
-!!! danger "Runtime assertion"
-
-    The precondition that a passed `#!cpp FILE` pointer must not be null is enforced with a
-    [runtime assertion](../../features/assertions.md).
+A UTF-8 byte order mark is silently ignored.
 
 ## Examples
 
@@ -102,6 +101,7 @@ Linear in the length of the input. The parser is a predictive LL(1) parser.
 
 - 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.
 
 !!! warning "Deprecation"
 

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

@@ -14,6 +14,11 @@ created from `args`.
 `Args`
 :   compatible types to create a `basic_json` object
 
+## Iterator invalidation
+
+For [`ordered_json`](../ordered_json.md), adding a value to an object can yield a reallocation, in which case all
+iterators (including the `end()` iterator) and all references to the elements are invalidated.
+
 ## Parameters
 
 `args` (in)

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

@@ -13,6 +13,12 @@ Creates a JSON value from the passed parameters `args` to the end of the JSON va
 `Args`
 :   compatible types to create a `basic_json` object
 
+## Iterator invalidation
+
+By adding an element to the end of the array, a reallocation can happen, in which case all iterators (including the
+[`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the [`end()`](end.md)
+iterator is invalidated.
+
 ## Parameters
 
 `args` (in)
@@ -48,6 +54,11 @@ Amortized constant.
     --8<-- "examples/emplace_back.output"
     ```
 
+## See also
+
+- [operator+=](operator+=.md) add a value to an array/object
+- [push_back](push_back.md) add a value to an array/object
+
 ## Version history
 
 - Since version 2.0.8.

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

@@ -8,24 +8,36 @@ This class is an extension of [`std::exception`](https://en.cppreference.com/w/c
 member `id` for exception ids. It is used as the base class for all exceptions thrown by the `basic_json` class. This
 class can hence be used as "wildcard" to catch exceptions, see example below.
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
-
-interface std::exception {}
-
-class basic_json::exception #FFFF00 {
-    + const int id
-    + const char* what() const
-}
-
-class basic_json::parse_error {
-    + const std::size_t byte
-}
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
+
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
+
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
+
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
+
+    style json_exception fill:#CCCCFF
 ```
 
 Subclasses:

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

@@ -37,7 +37,9 @@ Constant.
 
     The pointer becomes invalid if the underlying JSON object changes.
 
-    Consider the following example code where the pointer `ptr` changes after the array is resized. As a result, reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array element changes, because the underlying `std::vector` is resized after adding a fifth element.
+    Consider the following example code where the pointer `ptr` changes after the array is resized. As a result,
+    reading or writing to `ptr` after the array change would be undefined behavior. The address of the first array
+    element changes, because the underlying `std::vector` is resized after adding a fifth element.
 
     ```cpp
     #include <iostream>

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

@@ -42,7 +42,15 @@ class basic_json;
 
 ## Iterator invalidation
 
-Todo
+All operations that add values to an **array** ([`push_back`](push_back.md) , [`operator+=`](operator+=.md),
+[`emplace_back`](emplace_back.md), [`insert`](insert.md), and [`operator[]`](operator%5B%5D.md) for a non-existing
+index) can yield a reallocation, in which case all iterators (including the [`end()`](end.md) iterator) and all
+references to the elements are invalidated.
+
+For [`ordered_json`](../ordered_json.md), also all operations that add a value to an **object**
+([`push_back`](push_back.md), [`operator+=`](operator+=.md), [`emplace`](emplace.md), [`insert`](insert.md),
+[`update`](update.md), and [`operator[]`](operator%5B%5D.md) for a non-existing key) can yield a reallocation, in
+which case all iterators (including the [`end()`](end.md) iterator) and all references to the elements are invalidated.
 
 ## Requirements
 

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

@@ -24,6 +24,17 @@ void insert(const_iterator first, const_iterator last);
 4. Inserts elements from initializer list `ilist` into array before iterator `pos`.
 5. Inserts elements from range `[first, last)` into object.
 
+## Iterator invalidation
+
+For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators
+(including the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the
+[`end()`](end.md) iterator is invalidated. Also, any iterator or reference after the insertion point will point to the
+same index which is now a different value.
+
+For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again
+invalidates all iterators and all references. Also, any iterator or reference after the insertion point will point to
+the same index which is now a different value.
+
 ## Parameters
 
 `pos` (in)

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

@@ -8,26 +8,36 @@ This exception is thrown if iterators passed to a library function do not match
 
 Exceptions have ids 2xx (see [list of iterator errors](../../home/exceptions.md#iterator-errors)).
 
-```plantuml
-std::exception <|-- basic_json::exception
-basic_json::exception <|-- basic_json::parse_error
-basic_json::exception <|-- basic_json::invalid_iterator
-basic_json::exception <|-- basic_json::type_error
-basic_json::exception <|-- basic_json::out_of_range
-basic_json::exception <|-- basic_json::other_error
-
-interface std::exception {}
-
-class basic_json::exception {
-    + const int id
-    + const char* what() const
-}
-
-class basic_json::parse_error {
-    + const std::size_t byte
-}
-
-class basic_json::invalid_iterator #FFFF00 {}
+```mermaid
+classDiagram
+  direction LR
+  
+    class std_exception ["std::exception"] {
+        <<interface>>
+    }
+
+    class json_exception ["basic_json::exception"] {
+        +const int id
+        +const char* what() const
+    }
+    
+    class json_parse_error ["basic_json::parse_error"] {
+        +const std::size_t byte
+    }
+
+    class json_invalid_iterator ["basic_json::invalid_iterator"]
+    class json_type_error ["basic_json::type_error"]
+    class json_out_of_range ["basic_json::out_of_range"]
+    class json_other_error ["basic_json::other_error"]
+
+    std_exception <|-- json_exception
+    json_exception <|-- json_parse_error
+    json_exception <|-- json_invalid_iterator
+    json_exception <|-- json_type_error
+    json_exception <|-- json_out_of_range
+    json_exception <|-- json_other_error
+
+    style json_invalid_iterator fill:#CCCCFF
 ```
 
 ## Member functions

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

@@ -66,7 +66,7 @@ When iterating over an array, `key()` will return the index of the element as st
 !!! danger "Lifetime issues"
 
     Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exceeds the iteration. See
-    <https://github.com/nlohmann/json/issues/2040> for more information.
+    [#2040](https://github.com/nlohmann/json/issues/2040) for more information.
 
 ## Examples
 

docs/mkdocs/docs/api/basic_json/operator+=.md

@@ -27,6 +27,15 @@ reference operator+=(initializer_list_t init);
     `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`.
     Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`.
 
+## Iterator invalidation
+
+For all cases where an element is added to an **array**, a reallocation can happen, in which case all iterators (including
+the [`end()`](end.md) iterator) and all references to the elements are invalidated. Otherwise, only the
+[`end()`](end.md) iterator is invalidated.
+
+For [`ordered_json`](../ordered_json.md), also adding an element to an **object** can yield a reallocation which again
+invalidates all iterators and all references.
+
 ## Parameters
 
 `val` (in)
@@ -103,6 +112,11 @@ interpreted as `object_t::value_type` or `std::initializer_list<basic_json>`, se
     --8<-- "examples/push_back__initializer_list.output"
     ```
 
+## See also
+
+- [emplace_back](emplace_back.md) add a value to an array
+- [push_back](push_back.md) add a value to an array/object
+
 ## Version history
 
 1. Since version 1.0.0.

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -34,6 +34,15 @@ const_reference operator[](const json_pointer& ptr) const;
     [`string_t`](string_t.md) using  [`object_comparator_t`](object_comparator_t.md).
     This can also be a string view (C++17).
 
+## Iterator invalidation
+
+For the non-const versions 1. and 4., when passing an **array** index that does not exist, it is created and filled with
+a `#!json null` value before a reference to it is returned. For this, a reallocation can happen, in which case all
+iterators (including the [`end()`](end.md) iterator) and all references to the elements are invalidated.
+
+For [`ordered_json`](../ordered_json.md), also passing an **object key** to the non-const versions 2., 3., and 4., a
+reallocation can happen which again invalidates all iterators and all references.
+
 ## Parameters
 
 `idx` (in)