From 579c9359df68cc85a12a54673895ed5c188b05ca Mon Sep 17 00:00:00 2001
From: Benoit Blanchon <github@benoitblanchon.fr>
Date: Thu, 6 Nov 2014 16:08:06 +0100
Subject: [PATCH] Added comments

---
 include/ArduinoJson/Internals/JsonParser.hpp |  1 +
 include/ArduinoJson/JsonBuffer.hpp           | 51 +++++++++++++++++++-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/include/ArduinoJson/Internals/JsonParser.hpp b/include/ArduinoJson/Internals/JsonParser.hpp
index c8ac0b34..21403725 100644
--- a/include/ArduinoJson/Internals/JsonParser.hpp
+++ b/include/ArduinoJson/Internals/JsonParser.hpp
@@ -7,6 +7,7 @@
 #pragma once
 
 #include "../JsonBuffer.hpp"
+#include "../JsonVariant.hpp"
 
 namespace ArduinoJson {
 namespace Internals {
diff --git a/include/ArduinoJson/JsonBuffer.hpp b/include/ArduinoJson/JsonBuffer.hpp
index 5d285563..86b71228 100644
--- a/include/ArduinoJson/JsonBuffer.hpp
+++ b/include/ArduinoJson/JsonBuffer.hpp
@@ -6,24 +6,73 @@
 
 #pragma once
 
-#include "JsonVariant.hpp"
+#include <stddef.h>  // for size_t
+#include <stdint.h>  // for uint8_t
 
 namespace ArduinoJson {
 class JsonArray;
 class JsonObject;
 
+// Entry point for using the library.
+//
+// Handle the memory management (done in derived classes) and calls the parser.
+// This abstract class is implemented by StaticJsonBuffer which implements a
+// fixed memory allocation.
 class JsonBuffer {
  public:
   virtual ~JsonBuffer() {}
 
+  // Allocates an empty JsonArray.
+  //
+  // Returns a reference to the new JsonArray or JsonArray::invalid() if the
+  // allocation fails.
   JsonArray &createArray();
+
+  // Allocates an empty JsonObject.
+  //
+  // Returns a reference to the new JsonObject or JsonObject::invalid() if the
+  // allocation fails.
   JsonObject &createObject();
 
+  // Allocates and populate a JsonArray from a JSON string.
+  //
+  // The First argument is a pointer to the JSON string, the memory must be
+  // writable
+  // because the parser will insert null-terminators and replace escaped chars.
+  //
+  // The second argument set the nesting limit (see comment on DEFAULT_LIMIT)
+  //
+  // Returns a reference to the new JsonObject or JsonObject::invalid() if the
+  // allocation fails.
   JsonArray &parseArray(char *json, uint8_t nestingLimit = DEFAULT_LIMIT);
+
+  // Allocates and populate a JsonObject from a JSON string.
+  //
+  // The First argument is a pointer to the JSON string, the memory must be
+  // writable
+  // because the parser will insert null-terminators and replace escaped chars.
+  //
+  // The second argument set the nesting limit (see comment on DEFAULT_LIMIT)
+  //
+  // Returns a reference to the new JsonObject or JsonObject::invalid() if the
+  // allocation fails.
   JsonObject &parseObject(char *json, uint8_t nestingLimit = DEFAULT_LIMIT);
 
+  // Allocates n bytes in the JsonBuffer.
+  // Return a pointer to the allocated memory or NULL if allocation fails.
   virtual void *alloc(size_t size) = 0;
 
+  // Default value of nesting limit of parseArray() and parseObject().
+  //
+  // The nesting limit is a contain on the level of nesting allowed in the JSON
+  // string.
+  // If set to 0, only a flat array or objects can be parsed.
+  // If set to 1, the object can contain nested arrays or objects but only 1
+  // level deep.
+  // And bigger values will allow more level of nesting.
+  //
+  // The purpose of this feature is to prevent stack overflow that could lead to
+  // a security risk.
   static const uint8_t DEFAULT_LIMIT = 10;
 };
 }