deprecate current Builders

diff --git a/doc/jsoncpp.dox b/doc/jsoncpp.dox
index 91cd7e3..acde674 100644 (file)
--- 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 Json::CharReaderBuilder.
+std::cin >> root;
 
 // Get the value of the member of root named 'encoding', return 'UTF-8' if there is no
 // such member.
@@ -72,17 +72,21 @@ 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 Json::StreamWriterBuilder
+std::cout << root;
+// Of course, you can write to `std::ostringstream` if you prefer.
 
 // If desired, remember to add a linefeed and flush.
 std::cout << std::endl;
 \endcode
 
 \section _advanced Advanced usage
-
+We are finalizing the new *Builder* API, which will be in versions
+`1.4.0` and `0.8.0` when released. Until then, you may continue to
+use the old API, include `Writer`, `Reader`, and `Feature`.
 \code
-// Of course, you can write to `std::ostringstream` if you prefer. Or
-// use `writeString()` for convenience, with a specialized builder.
+
+// EXPERIMENTAL
+// Or use `writeString()` for convenience, with a specialized builder.
 Json::StreamWriterBuilder wbuilder;
 builder.indentation_ = "\t";
 std::string document = Json::writeString(root, wbuilder);
@@ -90,6 +94,7 @@ std::string document = Json::writeString(root, wbuilder);
 // You can also read into a particular sub-value.
 std::cin >> root["subtree"];
 
+// EXPERIMENTAL
 // Here we use a specialized Builder, discard comments, and
 // record errors.
 Json::CharReaderBuilder rbuilder;