From 61cc07ff384e92c09cbe288c8c1861d355658d35 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Fri, 27 Oct 2017 16:07:04 +0200
Subject: [PATCH] :memo: some documentation

---
 doc/Doxyfile |  2 +-
 doc/faq.md   | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 src/json.hpp | 17 +++++-----
 3 files changed, 96 insertions(+), 10 deletions(-)
 create mode 100644 doc/faq.md

diff --git a/doc/Doxyfile b/doc/Doxyfile
index 757a0103..bb38b979 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -107,7 +107,7 @@ WARN_LOGFILE           =
 # Configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT                  = ../src/json.hpp \
-                         index.md
+                         index.md faq.md
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          =
 RECURSIVE              = NO
diff --git a/doc/faq.md b/doc/faq.md
new file mode 100644
index 00000000..14125ee3
--- /dev/null
+++ b/doc/faq.md
@@ -0,0 +1,87 @@
+# FAQ
+
+## Parsing
+
+### How can I parse from a string?
+
+```cpp
+json j = json::parse("[1,2,3,4]");
+```
+
+You can pass string literals (as above), `std::string`, `const char*` or byte containers such as `std::vector<uint8_t>`.
+
+### How can I parse from a file?
+
+```cpp
+std::ifstream i("your_file.json");
+json j = json::parse(i);
+```
+
+## Serialization
+
+### How can I serialize a JSON value
+
+```cpp
+std::cout << j << std::endl;
+```
+
+This is equivalent to
+
+```cpp
+std::string s = j.dump();
+std::cout << s << std::endl;
+```
+
+### How can I pretty-print a JSON value
+
+```cpp
+std::cout << std::setw(4) << j << std::endl;
+```
+
+This is equivalent to
+
+```cpp
+std::string s = j.dump(4);
+std::cout << s << std::endl;
+```
+
+The number `4` denotes the number of spaces used for indentation.
+
+## Iterating
+
+### How can I iterate over a JSON value?
+
+```cpp
+for (json& val : j)
+{
+    // val is a reference for the current value
+}
+```
+
+This works with any JSON value, also primitive values like numbers.
+
+### How can I access the keys when iterating over a JSON object?
+
+```cpp
+for (auto it = j.begin(); it != j.end(); ++it)
+{
+    // the value
+    json &val = it.value();
+    
+    // the key (for objects)
+    const std::string &key = it.key();
+}
+```
+
+You can also use an iteration wrapper and use range for:
+
+```cpp
+for (auto it : json::iteration_wrapper(j))
+{
+    // the value
+    json &val = it.value();
+    
+    // the key (for objects)
+    const std::string &key = it.key();
+}
+```
diff --git a/src/json.hpp b/src/json.hpp
index d23d85b3..ccd43014 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -8160,13 +8160,11 @@ class basic_json
     @brief per-element parser callback type
 
     With a parser callback function, the result of parsing a JSON text can be
-    influenced. When passed to @ref parse(std::istream&, const
-    parser_callback_t) or @ref parse(const CharT, const parser_callback_t),
-    it is called on certain events (passed as @ref parse_event_t via parameter
-    @a event) with a set recursion depth @a depth and context JSON value
-    @a parsed. The return value of the callback function is a boolean
-    indicating whether the element that emitted the callback shall be kept or
-    not.
+    influenced. When passed to @ref parse, it is called on certain events
+    (passed as @ref parse_event_t via parameter @a event) with a set recursion
+    depth @a depth and context JSON value @a parsed. The return value of the
+    callback function is a boolean indicating whether the element that emitted
+    the callback shall be kept or not.
 
     We distinguish six scenarios (determined by the event type) in which the
     callback function can be called. The following table describes the values
@@ -8203,8 +8201,7 @@ class basic_json
     should be kept (`true`) or not (`false`). In the latter case, it is either
     skipped completely or replaced by an empty discarded object.
 
-    @sa @ref parse(std::istream&, parser_callback_t) or
-    @ref parse(const CharT, const parser_callback_t) for examples
+    @sa @ref parse for examples
 
     @since version 1.0.0
     */
@@ -12948,6 +12945,8 @@ class basic_json
     @param[in] cb  a parser callback function of type @ref parser_callback_t
     which is used to control the deserialization by filtering unwanted values
     (optional)
+    @param[in] allow_exceptions  whether to throw exceptions in case of a
+    parse error (optional, true by default)
 
     @return result of the deserialization