prefer ValueIterator::name() to ::memberName()

in case of embedded nulls

include/json/reader.h

@@ -110,7 +110,7 @@ public:
    *         during parsing.
    * \deprecated Use getFormattedErrorMessages() instead (typo fix).
    */
-  JSONCPP_DEPRECATED("Use getFormattedErrorMessages instead")
+  JSONCPP_DEPRECATED("Use getFormattedErrorMessages() instead.")
   std::string getFormatedErrorMessages() const;
 
   /** \brief Returns a user friendly string that list errors in the parsed
@@ -279,8 +279,6 @@ public:
 
 /** \brief Build a CharReader implementation.
 
-  \deprecated This is experimental and will be altered before the next release.
-
 Usage:
 \code
   using namespace Json;

include/json/value.h

@@ -667,16 +667,22 @@ public:
   /// Value.
   Value key() const;
 
-  /// Return the index of the referenced Value. -1 if it is not an arrayValue.
+  /// Return the index of the referenced Value, or -1 if it is not an arrayValue.
   UInt index() const;
 
+  /// Return the member name of the referenced Value, or "" if it is not an
+  /// objectValue.
+  /// \note Avoid `c_str()` on result, as embedded zeroes are possible.
+  std::string name() const;
+
   /// Return the member name of the referenced Value. "" if it is not an
   /// objectValue.
   /// \deprecated This cannot be used for UTF-8 strings, since there can be embedded nulls.
+  JSONCPP_DEPRECATED("Use `key = name();` instead.")
   char const* memberName() const;
   /// Return the member name of the referenced Value, or NULL if it is not an
   /// objectValue.
-  /// Better version than memberName(). Allows embedded nulls.
+  /// \note Better version than memberName(). Allows embedded nulls.
   char const* memberName(char const** end) const;
 
 protected:

include/json/writer.h

@@ -132,7 +132,7 @@ public:
 };
 
 /** \brief Abstract class for writers.
- * \deprecated Use StreamWriter.
+ * \deprecated Use StreamWriter. (And really, this is an implementation detail.)
  */
 class JSON_API Writer {
 public:
@@ -151,6 +151,7 @@ public:
  * \deprecated Use StreamWriterBuilder.
  */
 class JSON_API FastWriter : public Writer {
+
 public:
   FastWriter();
   virtual ~FastWriter() {}