📝 improved documentation for dump and iterator_wrapper

doc/examples/dump.cpp

@@ -28,4 +28,15 @@ int main()
     std::cout << "strings:" << '\n'
               << j_string.dump() << '\n'
               << j_string.dump(-1, ' ', true) << '\n';
+
+    // create JSON value with invalid UTF-8 byte sequence
+    json j_invalid = "\xF0\xA4\xAD\xC0";
+    try
+    {
+        std::cout << j_invalid.dump() << std::endl;
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
 }

doc/examples/dump.link

-<a target="_blank" href="https://wandbox.org/permlink/UnV6etCOZZRZpYyB"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="https://wandbox.org/permlink/mHH9TibITCYPpLwy"><b>online</b></a>
\ No newline at end of file

doc/examples/dump.output

@@ -50,3 +50,4 @@ arrays:
 strings:
 "Hellö 😀!"
 "Hell\u00f6 \ud83d\ude00!"
+[json.exception.type_error.316] invalid UTF-8 byte at index 3: 0xC0

src/json.hpp

@@ -11297,22 +11297,62 @@ class basic_json
     reference to the JSON values is returned, so there is no access to the
     underlying iterator.
 
+    For loop without iterator_wrapper:
+
+    @code{cpp}
+    for (auto it = j_object.begin(); it != j_object.end(); ++it)
+    {
+        std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
+    }
+    @endcode
+
+    Range-based for loop without iterator proxy:
+
+    @code{cpp}
+    for (auto it : j_object)
+    {
+        // "it" is of type json::reference and has no key() member
+        std::cout << "value: " << it << '\n';
+    }
+    @endcode
+
+    Range-based for loop with iterator proxy:
+
+    @code{cpp}
+    for (auto it : json::iterator_wrapper(j_object))
+    {
+        std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
+    }
+    @endcode
+
+    @note When iterating over an array, `key()` will return the index of the
+          element as string (see example).
+
+    @param[in] ref  reference to a JSON value
+    @return iteration proxy object wrapping @a ref with an interface to use in
+            range-based for loops
+
     @liveexample{The following code shows how the wrapper is used,iterator_wrapper}
 
+    @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+    changes in the JSON value.
+
+    @complexity Constant.
+
     @note The name of this function is not yet final and may change in the
     future.
     */
-    static iteration_proxy<iterator> iterator_wrapper(reference cont)
+    static iteration_proxy<iterator> iterator_wrapper(reference ref)
     {
-        return iteration_proxy<iterator>(cont);
+        return iteration_proxy<iterator>(ref);
     }
 
     /*!
     @copydoc iterator_wrapper(reference)
     */
-    static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
+    static iteration_proxy<const_iterator> iterator_wrapper(const_reference ref)
     {
-        return iteration_proxy<const_iterator>(cont);
+        return iteration_proxy<const_iterator>(ref);
     }
 
     /// @}