improve docs

including `writeString()`

doc/jsoncpp.dox

@@ -85,9 +85,8 @@ Json::StreamWriter::Builder builder;
 builder.withIndentation("   ");  // or whatever you like
 
 // Then build a StreamWriter.
-// (Of course, you can write to std::ostringstream if you prefer.)
 std::shared_ptr<Json::StreamWriter> writer(
-    builder.newStreamWriter( &std::cout );
+    builder.newStreamWriter( &std::cout ) );
 
 // Make a new JSON document for the configuration. Preserve original comments.
 writer->write( root );
@@ -95,6 +94,10 @@ writer->write( root );
 // If you like the defaults, you can insert directly into a stream.
 std::cout << root;
 
+// Of course, you can write to `std::ostringstream` if you prefer. Or
+// use `writeString()` for convenience.
+std::string document = Json::writeString( root, builder );
+
 // You can also read from a stream.  This will put the contents of any JSON
 // stream at a particular sub-value, if you'd like.
 std::cin >> root["subtree"];

include/json/writer.h

@@ -27,7 +27,7 @@ class StreamWriterBuilder;
 /**
 
 Usage:
-
+\code
   using namespace Json;
   Value value;
   StreamWriter::Builder builder;
@@ -36,16 +36,18 @@ Usage:
     builder.newStreamWriter(&std::cout));
   writer->write(value);
   std::cout.flush();
+\endcode
 */
 class JSON_API StreamWriter {
 protected:
   std::ostream& sout_;  // not owned; will not delete
 public:
-  /// `All`: Keep all comments.
+  /// Decide whether to write comments.
-  /// `None`: Drop all comments.
+  enum class CommentStyle {
-  /// Use `Most` to recover the odd behavior of previous versions.
+    None,  ///< Drop all comments.
-  /// Only `All` is currently implemented.
+    Most,  ///< Recover odd behavior of previous versions (not implemented yet).
-  enum class CommentStyle {None, Most, All};
+    All  ///< Keep all comments.
+  };
 
   /// Keep a reference, but do not take ownership of `sout`.
   StreamWriter(std::ostream* sout);