Added comment

include/ArduinoJson/JsonArray.hpp

@@ -18,29 +18,32 @@
 
 namespace ArduinoJson {
 
-// Forward declaration
+// Forward declarations
 class JsonObject;
 class JsonBuffer;
 
 // An array of JsonVariant.
-// Can be converted to a JSON string via JsonArray::printTo().
-// Can be extracted from a JSON string JsonBuffer::parseArray().
+//
+// The constructor is private, instances must be created via
+// JsonBuffer::createArray() or JsonBuffer::parseArray().
+// A JsonArray can be serialized to a JSON string via JsonArray::printTo().
+// It can also be deserialized from a JSON string via JsonBuffer::parseArray().
 class JsonArray : public Internals::JsonPrintable<JsonArray>,
                   public Internals::ReferenceType,
                   public Internals::List<JsonVariant> {
-  // JsonBuffer is a friend because it needs to call the private constructor of
-  // JsonArray from createArray() and parseArray().
+  // JsonBuffer is a friend because it needs to call the private constructor.
   friend class JsonBuffer;
 
  public:
-  // Returns the JsonVariant at the specified index (synonym for at())
-  value_type &operator[](int index) const { return at(index); }
-
   // Returns the JsonVariant at the specified index (synonym for operator[])
-  value_type &at(int index) const;
+  JsonVariant &at(int index) const;
+
+  // Returns the JsonVariant at the specified index (synonym for at())
+  JsonVariant &operator[](int index) const { return at(index); }
 
   // Adds an uninitialized JsonVariant at the end of the array.
-  value_type &add();
+  // Return a reference or JsonVariant::invalid() if allocation fails.
+  JsonVariant &add();
 
   // Adds the specified value at the end of the array.
   template <typename T>
@@ -67,16 +70,16 @@ class JsonArray : public Internals::JsonPrintable<JsonArray>,
   JsonObject &createNestedObject();
 
   // Returns a reference an invalid JsonArray.
+  // This object is meant to replace a NULL pointer.
   // This is used when memory allocation or JSON parsing fail.
   static JsonArray &invalid() { return _invalid; }
 
-  // Writes the array to a JsonWriter.
+  // Serialize the array to the specified JsonWriter.
   template <typename T>
   void writeTo(T &writer) const;
 
  private:
   // Create an empty JsonArray attached to the specified JsonBuffer.
-  // Constructor is private: instance must be created via a JsonBuffer
   explicit JsonArray(JsonBuffer *buffer) : List(buffer) {}
 
   // The instance returned by JsonArray::invalid()

include/ArduinoJson/JsonObject.hpp

@@ -11,54 +11,96 @@
 #include "Internals/ReferenceType.hpp"
 #include "JsonPair.hpp"
 
+// Returns the size (in bytes) of an object with n elements.
+// Can be very handy to determine the size of a StaticJsonBuffer.
 #define JSON_OBJECT_SIZE(NUMBER_OF_ELEMENTS) \
   (sizeof(JsonObject) + (NUMBER_OF_ELEMENTS) * sizeof(JsonObject::node_type))
 
 namespace ArduinoJson {
 
+// Forward declarations
 class JsonArray;
 class JsonBuffer;
 
+// A dictionary of JsonVariant indexed by string (char*)
+//
+// The constructor is private, instances must be created via
+// JsonBuffer::createObject() or JsonBuffer::parseObject().
+// A JsonObject can be serialized to a JSON string via JsonObject::printTo().
+// It can also be deserialized from a JSON string via JsonBuffer::parseObject().
 class JsonObject : public Internals::JsonPrintable<JsonObject>,
                    public Internals::ReferenceType,
                    public Internals::List<JsonPair> {
+  // JsonBuffer is a friend because it needs to call the private constructor.
   friend class JsonBuffer;
 
  public:
   typedef const char *key_type;
   typedef JsonPair value_type;
 
+  // Gets the JsonVariant associated with the specified key.
+  // Returns a reference or JsonVariant::invalid() if not found.
   JsonVariant &at(key_type key);
+
+  // Gets the JsonVariant associated with the specified key.
+  // Returns a constant reference or JsonVariant::invalid() if not found.
   const JsonVariant &at(key_type key) const;
+
+  // Gets or create the JsonVariant associated with the specified key.
+  // Returns a reference or JsonVariant::invalid() if allocation failed.
   JsonVariant &operator[](key_type key);
+
+  // Gets the JsonVariant associated with the specified key.
+  // Returns a constant reference or JsonVariant::invalid() if not found.
   const JsonVariant &operator[](key_type key) const { return at(key); }
 
-  void remove(key_type key);
+  // Adds an uninitialized JsonVariant associated with the specified key.
+  // Return a reference or JsonVariant::invalid() if allocation fails.
+  JsonVariant &add(key_type key) { return (*this)[key]; }
 
+  // Adds the specified key with the specified value.
   template <typename T>
   void add(key_type key, T value) {
     add(key).set(value);
   }
+
+  // Adds the specified key with a reference to the specified JsonArray.
   void add(key_type key, JsonArray &array) { add(key).set(array); }
+
+  // Adds the specified key with a reference to the specified JsonObject.
   void add(key_type key, JsonObject &object) { add(key).set(object); }
 
+  // Creates and adds a JsonArray.
+  // This is a shortcut for JsonBuffer::createArray() and JsonObject::add().
   JsonArray &createNestedArray(key_type key);
+
+  // Creates and adds a JsonObject.
+  // This is a shortcut for JsonBuffer::createObject() and JsonObject::add().
   JsonObject &createNestedObject(key_type key);
 
+  // Removes the specified key and the associated value.
+  void remove(key_type key);
+
+  // Returns a reference an invalid JsonObject.
+  // This object is meant to replace a NULL pointer.
+  // This is used when memory allocation or JSON parsing fail.
   static JsonObject &invalid() { return _invalid; }
 
   template <typename T>
   void writeTo(T &writer) const;
 
  private:
-  // constructor is private, instance must be created via JsonBuffer
+  // Create an empty JsonArray attached to the specified JsonBuffer.
   explicit JsonObject(JsonBuffer *buffer) : List(buffer) {}
 
-  JsonVariant &add(key_type key) { return (*this)[key]; }
-
+  // Returns the list node that matches the specified key.
   node_type *getNodeAt(key_type key) const;
+
+  // Returns the list node that matches the specified key, creating it if
+  // needed.
   node_type *getOrCreateNodeAt(key_type key);
 
+  // The instance returned by JsonObject::invalid()
   static JsonObject _invalid;
 };
 }

src/Internals/JsonParser.cpp

@@ -152,7 +152,7 @@ JsonObject &JsonParser::parseObject() {
 
     if (!skip(':')) break;  // colon is missing
 
-    JsonVariant &value = object[key];
+    JsonVariant &value = object.add(key);
 
     parseAnythingTo(value);
     if (!value.success()) break;  // value parsing failed