diff --git a/doc/jsoncpp.dox b/doc/jsoncpp.dox
index 5e34897..91cd7e3 100644
--- a/doc/jsoncpp.dox
+++ b/doc/jsoncpp.dox
@@ -51,7 +51,7 @@ preserved.
 
 \code
 Json::Value root;   // 'root' will contain the root value after parsing.
-std::cin >> root;   // Or see CharReaderBuilder.
+std::cin >> root;   // Or see Json::CharReaderBuilder.
 
 // Get the value of the member of root named 'encoding', return 'UTF-8' if there is no
 // such member.
@@ -72,17 +72,30 @@ root["indent"]["length"] = getCurrentIndentLength();
 root["indent"]["use_space"] = getCurrentIndentUseSpace();
 
 // If you like the defaults, you can insert directly into a stream.
-std::cout << root;  // Or see StreamWriterBuilder.
+std::cout << root;  // Or see Json::StreamWriterBuilder
 
 // If desired, remember to add a linefeed and flush.
 std::cout << std::endl;
+\endcode
 
+\section _advanced Advanced usage
+
+\code
 // Of course, you can write to `std::ostringstream` if you prefer. Or
-// use `writeString()` for convenience.
-std::string document = Json::writeString( root, builder );
+// use `writeString()` for convenience, with a specialized builder.
+Json::StreamWriterBuilder wbuilder;
+builder.indentation_ = "\t";
+std::string document = Json::writeString(root, wbuilder);
 
 // You can also read into a particular sub-value.
 std::cin >> root["subtree"];
+
+// Here we use a specialized Builder, discard comments, and
+// record errors.
+Json::CharReaderBuilder rbuilder;
+rbuilder.collectComments_ = false;
+std::string errs;
+Json::parseFromStream(rbuilder, std::cin, &root["subtree"], &errs);
 \endcode
 
 \section _pbuild Build instructions
diff --git a/include/json/reader.h b/include/json/reader.h
index 7dc9761..68b3738 100644
--- a/include/json/reader.h
+++ b/include/json/reader.h
@@ -28,6 +28,7 @@ namespace Json {
 /** \brief Unserialize a <a HREF="http://www.json.org">JSON</a> document into a
  *Value.
  *
+ * \deprecated Use CharReader and CharReaderBuilder.
  */
 class JSON_API Reader {
 public:
@@ -280,17 +281,23 @@ Usage:
 \code
   using namespace Json;
   CharReaderBuilder builder;
-  builder.collectComments_ = true;
-  std::shared_ptr<CharReader> reader(
-    builder.newCharReader());
+  builder.collectComments_ = false;
   Value value;
   std::string errs;
-  bool ok = parseFromStream(std::cin, &value, &errs);
+  bool ok = parseFromStream(builder, std::cin, &value, &errs);
 \endcode
 */
 class CharReaderBuilder : public CharReader::Factory {
 public:
+  /** default: true
+   *
+   * It is possible to "allow" comments but still not "collect" them.
+   */
   bool collectComments_;
+  /** default: all()
+   *
+   * For historical reasons, Features is a separate structure.
+   */
   Features features_;
 
   CharReaderBuilder();