From 314e4e7699087b96c6fbdc4d8d3458ef11a2a16c Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Sat, 16 Dec 2017 23:58:10 +0100
Subject: [PATCH] :memo: improved documentation for dump and iterator_wrapper

---
 doc/examples/dump.cpp    | 11 +++++++++
 doc/examples/dump.link   |  2 +-
 doc/examples/dump.output |  1 +
 src/json.hpp             | 48 ++++++++++++++++++++++++++++++++++++----
 4 files changed, 57 insertions(+), 5 deletions(-)

diff --git a/doc/examples/dump.cpp b/doc/examples/dump.cpp
index 4440f91c..1c485972 100644
--- a/doc/examples/dump.cpp
+++ b/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;
+    }
 }
diff --git a/doc/examples/dump.link b/doc/examples/dump.link
index c02a4126..4de70343 100644
--- a/doc/examples/dump.link
+++ b/doc/examples/dump.link
@@ -1 +1 @@
-<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
diff --git a/doc/examples/dump.output b/doc/examples/dump.output
index 8c6998bb..c94eeb02 100644
--- a/doc/examples/dump.output
+++ b/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
diff --git a/src/json.hpp b/src/json.hpp
index 8cc3c4a5..31429f81 100644
--- a/src/json.hpp
+++ b/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);
     }
 
     /// @}