📝 some documentation

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

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();
+}
+```

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
+    influenced. When passed to @ref parse, it is called on certain events
-    parser_callback_t) or @ref parse(const CharT, const parser_callback_t),
+    (passed as @ref parse_event_t via parameter @a event) with a set recursion
-    it is called on certain events (passed as @ref parse_event_t via parameter
+    depth @a depth and context JSON value @a parsed. The return value of the
-    @a event) with a set recursion depth @a depth and context JSON value
+    callback function is a boolean indicating whether the element that emitted
-    @a parsed. The return value of the callback function is a boolean
+    the callback shall be kept or not.
-    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
+    @sa @ref parse for examples
-    @ref parse(const CharT, const parser_callback_t) 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