Added comments

include/ArduinoJson/Internals/List.hpp

@@ -13,6 +13,9 @@
 namespace ArduinoJson {
 namespace Internals {
 
+// A singly linked list of T.
+// The linked list is composed of ListNode<T>.
+// It is derived by JsonArray and JsonObject
 template <typename T>
 class List {
  public:
@@ -21,9 +24,21 @@ class List {
   typedef ListIterator<T> iterator;
   typedef ListConstIterator<T> const_iterator;
 
+  // Creates an empty List<T> attached to a JsonBuffer.
+  // The JsonBuffer allows to allocate new nodes.
+  // When buffer is NULL, the List is not able to grow and success() returns
+  // false. This is used to identify bad memory allocations and parsing
+  // failures.
   explicit List(JsonBuffer *buffer) : _buffer(buffer), _firstNode(NULL) {}
 
+  // Returns true if the object is valid
+  // Would return false in the following situation:
+  // - the memory allocation failed (StaticJsonBuffer was too small)
+  // - the JSON parsing failed
   bool success() const { return _buffer != NULL; }
+
+  // Returns the numbers of elements in the list.
+  // For a JsonObject, it would return the number of key-value pairs
   int size() const;
 
   iterator begin() { return iterator(_firstNode); }

include/ArduinoJson/Internals/ListConstIterator.hpp

@@ -9,6 +9,7 @@
 namespace ArduinoJson {
 namespace Internals {
 
+// A read-only forward itertor for List<T>
 template <typename T>
 class ListConstIterator {
  public:

include/ArduinoJson/Internals/ListIterator.hpp

@@ -11,6 +11,7 @@
 namespace ArduinoJson {
 namespace Internals {
 
+// A read-write forward iterator for List<T>
 template <typename T>
 class ListIterator {
  public:

include/ArduinoJson/Internals/ListNode.hpp

@@ -11,6 +11,8 @@
 namespace ArduinoJson {
 namespace Internals {
 
+// A node for a singly-linked list.
+// Used by List<T> and its iterators.
 template <typename T>
 struct ListNode {
   ListNode() : next(NULL) {}

include/ArduinoJson/Internals/PlacementNew.hpp

@@ -6,6 +6,8 @@
 
 #ifdef ARDUINO
 
+// Declares the placement new as in <new>.
+// This is required for Arduino IDE because it doesn't include the <new> header.
 inline void *operator new(size_t, void *p) throw() { return p; }
 
 #else

include/ArduinoJson/Internals/PrettyJsonWriter.hpp

@@ -12,6 +12,7 @@
 namespace ArduinoJson {
 namespace Internals {
 
+// An indented version of JsonWriter.
 class PrettyJsonWriter : public JsonWriter {
  public:
   explicit PrettyJsonWriter(IndentedPrint *sink)

include/ArduinoJson/Internals/QuotedString.hpp

@@ -11,9 +11,18 @@
 namespace ArduinoJson {
 namespace Internals {
 
+// An helper class to print and extract doubly-quoted strings
 class QuotedString {
  public:
+  // Writes a doubly-quote string to a Print implementation.
+  // It adds the double quotes (") at the beginning and the end of the string.
+  // It escapes the special characters as required by the JSON specifications.
   static size_t printTo(const char *, Print *);
+
+  // Reads a doubly-quoted string from a buffer.
+  // It removes the double quotes (").
+  // It unescapes the special character as required by the JSON specification,
+  // with the exception of the Unicode characters (\u0000).
   static char *extractFrom(char *input, char **end);
 };
 }