Added comments

JsonParser/JsonPair.h

@@ -19,7 +19,6 @@ namespace ArduinoJson
             JsonPair(JsonToken token)
                 : JsonToken(token)
             {
-
             }
 
             // Get the key
@@ -35,4 +34,4 @@ namespace ArduinoJson
             }
         };
     }
-}
+}

JsonParser/JsonParser.h

@@ -1,7 +1,7 @@
 /*
 * Arduino JSON library
 * Benoit Blanchon 2014 - MIT License
-*/
+*/
 
 #pragma once
 
@@ -11,19 +11,14 @@ namespace ArduinoJson
 {
     namespace Parser
     {
-        /*
-        * The JSON parser.
-        *
-        * You need to specifiy the number of token to be allocated for that parser.
-        * Values from 16 to 32 are recommended.
-        * The parser size will be MAX_TOKEN*8 bytes.
-        * Don't forget that the memory size of standard Arduino board is only 2KB
-        *
-        * CAUTION: JsonArray and JsonHashTable contain pointers to tokens of the
-        * JsonParser, so they need the JsonParser to be in memory to work.
-        * As a result, you must not create JsonArray and JsonHashTable that have a
-        * longer life that the JsonParser.
-        */
+        // The JSON parser.
+        //
+        // You need to specifiy the number of token to be allocated for that parser.
+        //
+        // CAUTION: JsonArray, JsonObject and JsonValue contain pointers to tokens of the
+        // JsonParser, so they need the JsonParser to be in memory to work.
+        // As a result, you must not create JsonArray, JsonObject or JsonValue that have a
+        // longer life that the JsonParser.
         template <int MAX_TOKENS>
         class JsonParser : public JsonParserBase
         {

JsonParser/JsonParserBase.h

@@ -1,7 +1,7 @@
 /*
 * Arduino JSON library
 * Benoit Blanchon 2014 - MIT License
-*/
+*/
 
 #pragma once
 
@@ -12,34 +12,30 @@ namespace ArduinoJson
 {
     namespace Parser
     {
+        // Base class for the JSON parser, in case you want to provide your own buffer
         class JsonParserBase
         {
         public:
 
+            // Create a JSON parser using the provided buffer
             JsonParserBase(jsmntok_t* tokens, int maxTokens)
                 : tokens(tokens), maxTokens(maxTokens)
             {
             }
 
+            // Parse the JSON string and return a array
+            //
+            // The content of the string may be altered to add '\0' at the
+            // end of string tokens            
             JsonValue parse(char* json);
 
-            /*
-            * Parse the JSON string and return a array.
-            *
-            * The content of the string may be altered to add '\0' at the
-            * end of string tokens
-            */
+            // Obsolete: use parse() instead
             DEPRECATED JsonArray parseArray(char* json)
             {
                 return parse(json);
             }
 
-            /*
-            * Parse the JSON string and return a array.
-            *
-            * The content of the string may be altered to add '\0' at the
-            * end of string tokens
-            */
+            // Obsolete: use parse() instead
             DEPRECATED JsonObject parseHashTable(char* json)
             {
                 return parse(json);

JsonParser/JsonToken.h

@@ -11,73 +11,85 @@ namespace ArduinoJson
 {
     namespace Parser
     {
+        // A pointer to a JSON token
         class JsonToken
         {
         public:
 
+            // Create a "null" pointer
             JsonToken()
                 : token(0)
             {
-
             }
 
+            // Create a pointer to the specified JSON token
             JsonToken(char* json, jsmntok_t* token)
-                : json(json),  token(token)
+                : json(json), token(token)
             {
-
             }
 
+            // Get content of the JSON token
             char* getText()
             {
                 json[token->end] = 0;
                 return json + token->start;
             }
 
+            // Get the number of children tokens
+            int childrenCount()
+            {
+                return token->size;
+            }
+
+            // Get a pointer to the first child of the current token
             JsonToken firstChild() const
             {
                 return JsonToken(json, token + 1);
             }
 
+            // Get a pointer to the next sibling token (ie skiping the children tokens)
             JsonToken nextSibling() const;
 
-            bool operator!= (const JsonToken& other) const
+            // Test equality
+            bool operator!=(const JsonToken& other) const
             {
                 return token != other.token;
             }
 
-            static JsonToken null()
-            {
-                return JsonToken(0, 0);
-            }
-
+            // Tell if the pointer is "null"
             bool isValid()
             {
                 return token != 0;
             }
 
+            // Tell if the JSON token is a JSON object
             bool isObject()
             {
                 return token != 0 && token->type == JSMN_OBJECT;
             }
 
+            // Tell if the JSON token is a JSON array
             bool isArray()
             {
                 return token != 0 && token->type == JSMN_ARRAY;
             }
 
+            // Tell if the JSON token is a primitive
             bool isPrimitive()
             {
                 return token != 0 && token->type == JSMN_PRIMITIVE;
             }
 
+            // Tell if the JSON token is a string
             bool isString()
             {
                 return token != 0 && token->type == JSMN_STRING;
             }
 
-            int childrenCount()
+            // Explicit wait to create a "null" JsonToken
+            static JsonToken null()
             {
-                return token->size;
+                return JsonToken();
             }
 
         private:
@@ -85,5 +97,4 @@ namespace ArduinoJson
             jsmntok_t* token;
         };
     }
-}
-
+}

JsonParser/JsonValue.h

@@ -1,52 +1,72 @@
 /*
  * Arduino JSON library
  * Benoit Blanchon 2014 - MIT License
- */
-
-#pragma once
-
-#include "JsonToken.h"
+ */
 
-#ifndef ARDUINO_JSON_NO_DEPRECATED_WARNING
+#pragma once
+
+#include "JsonToken.h"
+
+#ifndef ARDUINO_JSON_NO_DEPRECATED_WARNING
 #ifdef __GNUC__
 #define DEPRECATED __attribute__((deprecated))
 #elif defined(_MSC_VER)
 #define DEPRECATED __declspec(deprecated)
-#endif
+#endif
 #else
 #define DEPRECATED
-#endif
-
-namespace ArduinoJson
-{
-    namespace Parser
-    {
-        class JsonValue : protected JsonToken
-        {
+#endif
+
+namespace ArduinoJson
+{
+    namespace Parser
+    {
+        // A JSON value
+        // Can be converted to string, double, bool, array or object.
+        class JsonValue : protected JsonToken
+        {
         public:
 
+            // Create a invalid value
             JsonValue()
             {
-
             }
 
+            // Convert a JsonToken to a JsonValue
             JsonValue(JsonToken token)
                 : JsonToken(token)
             {
-
             }
 
+            // Tell is the JsonValue is valid
             bool success()
             {
                 return isValid();
             }
-            
-            operator bool();
-            operator double();
-            operator long();
-            operator char*();
-            JsonValue operator[](int index);
-            JsonValue operator[](const char*key);
-        };
-    }
+
+            // Convert the JsonValue to a bool.
+            // Returns false if the JsonValue is not a boolean.
+            operator bool();
+
+            // Convert the JsonValue to a floating point value.
+            // Returns false if the JsonValue is not a number.
+            operator double();
+
+            // Convert the JsonValue to a long integer.
+            // Returns 0 if the JsonValue is not a number.
+            operator long();
+
+            // Convert the JsonValue to a string.
+            // Returns 0 if the JsonValue is not a string.
+            operator char*();            
+            
+            // Get the nested value at the specified index.            
+            // Returns an invalid JsonValue if the current value is not an array.
+            JsonValue operator[](int index);
+
+            // Get the nested value matching the specified index.            
+            // Returns an invalid JsonValue if the current value is not an object.
+            JsonValue operator[](const char* key);
+        };
+    }
 }