remark defaults via doxygen snippet

cdunn2001 · cdunn2001 · commit 3cf9175bde9b · 2015-02-09T18:16:24.000-06:00
diff --git a/doc/jsoncpp.dox b/doc/jsoncpp.dox
@@ -103,6 +103,22 @@ std::string errs;
 bool ok = Json::parseFromStream(rbuilder, std::cin, &root, &errs);
 \endcode
 
+Yes, compile-time configuration-checking would be helpful,
+but `Json::Value` lets you
+write and read the builder configuration, which is better! In other words,
+you can configure your JSON parser using JSON.
+
+CharReaders and StreamWriters are not thread-safe, but they are re-usable.
+\code
+Json::CharReaderBuilder rbuilder;
+cfg >> rbuilder.settings_;
+std::unique_ptr<Json::CharReader> const reader(rbuilder.newCharReader());
+reader->parse(start, stop, &value1, &errs);
+// ...
+reader->parse(start, stop, &value2, &errs);
+// etc.
+\endcode
+
 \section _pbuild Build instructions
 The build instructions are located in the file 
 <a HREF="https://github.com/open-source-parsers/jsoncpp/blob/master/README.md">README.md</a> in the top-directory of the project.
@@ -137,5 +153,7 @@ and recognized in your jurisdiction.
 
 \author Baptiste Lepilleur <blep@users.sourceforge.net> (originator)
 \version \include version
+We make strong guarantees about binary-compatibility, consistent with
+<a href="http://apr.apache.org/versioning.html">the Apache versioning scheme</a>.
 \sa version.h
 */
diff --git a/include/json/reader.h b/include/json/reader.h
@@ -296,12 +296,14 @@ class JSON_API CharReaderBuilder : public CharReader::Factory {
   // Note: We use a Json::Value so that we can add data-members to this class
   // without a major version bump.
   /** Configuration of this builder.
+    These are case-sensitive.
     Available settings (case-sensitive):
     - "collectComments": false or true (default=true)
     - TODO: other features ...
-    But don't trust these docs. You can examine 'settings_` yourself
+    You can examine 'settings_` yourself
     to see the defaults. You can also write and read them just like any
     JSON Value.
+    \sa setDefaults(Json::Value*)
     */
   Json::Value settings_;
 
@@ -316,8 +318,16 @@ class JSON_API CharReaderBuilder : public CharReader::Factory {
   bool validate(Json::Value* invalid) const;
   /** Called by ctor, but you can use this to reset settings_.
    * \pre 'settings' != NULL (but Json::null is fine)
+   * \remark Defaults:
+   * \snippet src/lib_json/json_reader.cpp CharReaderBuilderStrictMode
    */
   static void setDefaults(Json::Value* settings);
+  /** Same as old Features::strictMode().
+   * \pre 'settings' != NULL (but Json::null is fine)
+   * \remark Defaults:
+   * \snippet src/lib_json/json_reader.cpp CharReaderBuilderDefaults
+   */
+  static void strictMode(Json::Value* settings);
 };
 
 /** Consume entire stream and use its begin/end.
diff --git a/include/json/writer.h b/include/json/writer.h
@@ -121,6 +121,8 @@ class JSON_API StreamWriterBuilder : public StreamWriter::Factory {
   bool validate(Json::Value* invalid) const;
   /** Called by ctor, but you can use this to reset settings_.
    * \pre 'settings' != NULL (but Json::null is fine)
+   * \remark Defaults:
+   * \snippet src/lib_json/json_writer.cpp StreamWriterBuilderDefaults
    */
   static void setDefaults(Json::Value* settings);
 };
diff --git a/src/lib_json/json_reader.cpp b/src/lib_json/json_reader.cpp
@@ -952,9 +952,25 @@ bool CharReaderBuilder::validate(Json::Value* invalid) const
   return valid;
 }
 // static
+void CharReaderBuilder::strictMode(Json::Value* settings)
+{
+//! [CharReaderBuilderStrictMode]
+  (*settings)["allowComments"] = false;
+  (*settings)["strictRoot"] = true;
+  (*settings)["allowDroppedNullPlaceholders"] = false;
+  (*settings)["allowNumericKeys"] = false;
+//! [CharReaderBuilderStrictMode]
+}
+// static
 void CharReaderBuilder::setDefaults(Json::Value* settings)
 {
+//! [CharReaderBuilderDefaults]
   (*settings)["collectComments"] = true;
+  (*settings)["allowComments"] = true;
+  (*settings)["strictRoot"] = false;
+  (*settings)["allowDroppedNullPlaceholders"] = false;
+  (*settings)["allowNumericKeys"] = false;
+//! [CharReaderBuilderDefaults]
 }
 
 //////////////////////////////////
diff --git a/src/lib_json/json_writer.cpp b/src/lib_json/json_writer.cpp
@@ -1008,8 +1008,10 @@ bool StreamWriterBuilder::validate(Json::Value* invalid) const
 // static
 void StreamWriterBuilder::setDefaults(Json::Value* settings)
 {
+  //! [StreamWriterBuilderDefaults]
   (*settings)["commentStyle"] = "All";
   (*settings)["indentation"] = "\t";
+  //! [StreamWriterBuilderDefaults]
 }
 
 /*

Original file line number	Diff line number	Diff line change
`@@ -1008,8 +1008,10 @@ bool StreamWriterBuilder::validate(Json::Value* invalid) const`
`1008`	`1008`	`// static`
`1009`	`1009`	`void StreamWriterBuilder::setDefaults(Json::Value* settings)`
`1010`	`1010`	`{`
	`1011`	`+ //! [StreamWriterBuilderDefaults]`
`1011`	`1012`	`(*settings)["commentStyle"] = "All";`
`1012`	`1013`	`(*settings)["indentation"] = "\t";`
	`1014`	`+ //! [StreamWriterBuilderDefaults]`
`1013`	`1015`	`}`
`1014`	`1016`
`1015`	`1017`	`/*`