Adjust JSON Pointer examples (#3622)

* 📝 adjust JSON Pointer examples

* 👷 add test for documentation

* 📝 note platform-dependent output on some examples

.github/workflows/ubuntu.yml

@@ -147,3 +147,12 @@ jobs:
         run:  python -m pip install reuse
       - name: REUSE lint
         run: reuse lint
+
+  ci_test_documentation:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: cmake
+        run: cmake -S . -B build -DJSON_CI=On
+      - name: build
+        run: cmake --build build --target ci_test_documentation

cmake/ci.cmake

@@ -934,6 +934,16 @@ add_custom_target(ci_icpc
     COMMENT "Compile and test with ICPC"
 )
 
+###############################################################################
+# test documentation
+###############################################################################
+
+add_custom_target(ci_test_documentation
+    COMMAND make check_output_portable -j8
+    WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/docs
+    COMMENT "Check that all examples compile and create the desired output"
+)
+
 ###############################################################################
 # Clean up all generated files.
 ###############################################################################

docs/Makefile

@@ -11,13 +11,13 @@ EXAMPLES = $(wildcard examples/*.cpp)
 
 # create output from a stand-alone example file
 %.output: %.cpp
-	make $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=c++11"
+	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=c++11"
 	./$(<:.cpp=) > $@
 	rm $(<:.cpp=)
 
 # compare created output with current output of the example files
 %.test: %.cpp
-	make $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=c++11"
+	$(MAKE) $(<:.cpp=) CPPFLAGS="-I $(SRCDIR)" CXXFLAGS="-std=c++11"
 	./$(<:.cpp=) > $@
 	diff $@ $(<:.cpp=.output)
 	rm $(<:.cpp=) $@
@@ -28,6 +28,10 @@ create_output: $(EXAMPLES:.cpp=.output)
 # check output of all stand-alone example files
 check_output: $(EXAMPLES:.cpp=.test)
 
+# check output of all stand-alone example files (exclude files with platform-dependent output.)
+# This target is used in the CI (ci_test_documentation).
+check_output_portable: $(filter-out examples/meta.test examples/max_size.test examples/std_hash.test examples/basic_json__CompatibleType.test,$(EXAMPLES:.cpp=.test))
+
 clean:
 	rm -fr $(EXAMPLES:.cpp=)
 	$(MAKE) clean -C docset

docs/examples/json_pointer__back.cpp

@@ -10,6 +10,6 @@ int main()
     json::json_pointer ptr2("/foo/0");
 
     // call empty()
-    std::cout << "last reference token of " << ptr1 << " is " << ptr1.back() << '\n'
+    std::cout << "last reference token of \"" << ptr1 << "\" is \"" << ptr1.back() << "\"\n"
-              << "last reference token of " << ptr2 << " is " << ptr2.back() << std::endl;
+              << "last reference token of \"" << ptr2 << "\" is \"" << ptr2.back() << "\"" << std::endl;
 }

docs/examples/json_pointer__back.output

@@ -1,2 +1,2 @@
-last reference token of "/foo" is foo
+last reference token of "/foo" is "foo"
-last reference token of "/foo/0" is 0
+last reference token of "/foo/0" is "0"

docs/examples/json_pointer__empty.cpp

@@ -13,8 +13,8 @@ int main()
 
     // call empty()
     std::cout << std::boolalpha
-              << ptr0 << ": " << ptr0.empty() << '\n'
+              << "\"" << ptr0 << "\": " << ptr0.empty() << '\n'
-              << ptr1 << ": " << ptr1.empty() << '\n'
+              << "\"" << ptr1 << "\": " << ptr1.empty() << '\n'
-              << ptr2 << ": " << ptr2.empty() << '\n'
+              << "\"" << ptr2 << "\": " << ptr2.empty() << '\n'
-              << ptr3 << ": " << ptr3.empty() << std::endl;
+              << "\"" << ptr3 << "\": " << ptr3.empty() << std::endl;
 }

docs/examples/json_pointer__operator_add.cpp

@@ -7,17 +7,17 @@ int main()
 {
     // create a JSON pointer
     json::json_pointer ptr("/foo");
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     // append a JSON Pointer
     ptr /= json::json_pointer("/bar/baz");
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     // append a string
     ptr /= "fob";
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     // append an array index
     ptr /= 42;
-    std::cout << ptr << std::endl;
+    std::cout << "\"" << ptr << "\"" << std::endl;
 }

docs/examples/json_pointer__operator_add_binary.cpp

@@ -9,11 +9,11 @@ int main()
     json::json_pointer ptr("/foo");
 
     // append a JSON Pointer
-    std::cout << ptr / json::json_pointer("/bar/baz") << '\n';
+    std::cout << "\"" << ptr / json::json_pointer("/bar/baz") << "\"\n";
 
     // append a string
-    std::cout << ptr / "fob" << '\n';
+    std::cout << "\"" << ptr / "fob" << "\"\n";
 
     // append an array index
-    std::cout << ptr / 42 << std::endl;
+    std::cout << "\"" << ptr / 42 << "\"" << std::endl;
 }

docs/examples/json_pointer__parent_pointer.cpp

@@ -12,7 +12,7 @@ int main()
 
     // call parent_pointer()
     std::cout << std::boolalpha
-              << "parent of " << ptr1 << " is " << ptr1.parent_pointer() << '\n'
+              << "parent of \"" << ptr1 << "\" is \"" << ptr1.parent_pointer() << "\"\n"
-              << "parent of " << ptr2 << " is " << ptr2.parent_pointer() << '\n'
+              << "parent of \"" << ptr2 << "\" is \"" << ptr2.parent_pointer() << "\"\n"
-              << "parent of " << ptr3 << " is " << ptr3.parent_pointer() << std::endl;
+              << "parent of \"" << ptr3 << "\" is \"" << ptr3.parent_pointer() << "\"" << std::endl;
 }

docs/examples/json_pointer__pop_back.cpp

@@ -7,15 +7,15 @@ int main()
 {
     // create empty JSON Pointer
     json::json_pointer ptr("/foo/bar/baz");
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     // call pop_back()
     ptr.pop_back();
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     ptr.pop_back();
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     ptr.pop_back();
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 }

docs/examples/json_pointer__push_back.cpp

@@ -7,15 +7,15 @@ int main()
 {
     // create empty JSON Pointer
     json::json_pointer ptr;
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     // call push_back()
     ptr.push_back("foo");
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     ptr.push_back("0");
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 
     ptr.push_back("bar");
-    std::cout << ptr << '\n';
+    std::cout << "\"" << ptr << "\"\n";
 }

docs/examples/json_pointer__to_string.cpp

@@ -19,16 +19,16 @@ int main()
     json::json_pointer ptr11("/ ");
     json::json_pointer ptr12("/m~0n");
 
-    std::cout << ptr1.to_string() << '\n'
+    std::cout << "\"" << ptr1.to_string() << "\"\n"
-              << ptr2.to_string() << '\n'
+              << "\"" << ptr2.to_string() << "\"\n"
-              << ptr3.to_string() << '\n'
+              << "\"" << ptr3.to_string() << "\"\n"
-              << ptr4.to_string() << '\n'
+              << "\"" << ptr4.to_string() << "\"\n"
-              << ptr5.to_string() << '\n'
+              << "\"" << ptr5.to_string() << "\"\n"
-              << ptr6.to_string() << '\n'
+              << "\"" << ptr6.to_string() << "\"\n"
-              << ptr7.to_string() << '\n'
+              << "\"" << ptr7.to_string() << "\"\n"
-              << ptr8.to_string() << '\n'
+              << "\"" << ptr8.to_string() << "\"\n"
-              << ptr9.to_string() << '\n'
+              << "\"" << ptr9.to_string() << "\"\n"
-              << ptr10.to_string() << '\n'
+              << "\"" << ptr10.to_string() << "\"\n"
-              << ptr11.to_string() << '\n'
+              << "\"" << ptr11.to_string() << "\"\n"
-              << ptr12.to_string() << std::endl;
+              << "\"" << ptr12.to_string() << "\"" << std::endl;
 }

docs/examples/json_pointer__to_string.output

@@ -1,12 +1,12 @@
-
+""
-/foo
+"/foo"
-/foo/0
+"/foo/0"
-/
+"/"
-/a~1b
+"/a~1b"
-/c%d
+"/c%d"
-/e^f
+"/e^f"
-/g|h
+"/g|h"
-/i\j
+"/i\j"
-/k"l
+"/k"l"
-/ 
+"/ "
-/m~0n
+"/m~0n"

docs/examples/patch_inplace.cpp

@@ -30,5 +30,5 @@ int main()
     doc.patch_inplace(patch);
 
     // output patched document
-    std::cout << "After\n" << std::setw(4) << doc << std::endl;
+    std::cout << "\nAfter\n" << std::setw(4) << doc << std::endl;
 }

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

@@ -317,6 +317,8 @@ basic_json(basic_json&& other) noexcept;
     --8<-- "examples/basic_json__CompatibleType.output"
     ```
 
+    Note the output is platform-dependent.
+
 ??? example "Example: (5) create a container (array or object) from an initializer list"
 
     The example below shows how JSON values are created from initializer lists.

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

@@ -40,7 +40,7 @@ string elements the JSON value can store which is `1`.
 
 ??? example
 
-    The following code calls `max_size()` on the different value types. Note the output is implementation specific.
+    The following code calls `max_size()` on the different value types.
         
     ```cpp
     --8<-- "examples/max_size.cpp"
@@ -52,6 +52,8 @@ string elements the JSON value can store which is `1`.
     --8<-- "examples/max_size.output"
     ```
 
+    Note the output is platform-dependent.
+
 ## Version history
 
 - Added in version 1.0.0.

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

@@ -32,8 +32,7 @@ Constant.
 
 ??? example
 
-    The following code shows an example output of the `meta()`
+    The following code shows an example output of the `meta()` function.
-    function.
     
     ```cpp
     --8<-- "examples/meta.cpp"
@@ -45,6 +44,8 @@ Constant.
     --8<-- "examples/meta.output"
     ```
 
+    Note the output is platform-dependent.
+
 ## See also
 
 - [**NLOHMANN_JSON_VERSION_MAJOR**/**NLOHMANN_JSON_VERSION_MINOR**/**NLOHMANN_JSON_VERSION_PATCH**](../macros/nlohmann_json_version_major.md) - library version information

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

@@ -26,6 +26,8 @@ type of the JSON value is taken into account to have different hash values for `
     --8<-- "examples/std_hash.output"
     ```
 
+    Note the output is platform-dependent.
+
 ## Version history
 
 - Added in version 1.0.0.