From 79bfe731afab62ef4a89f568e8c361d19c826e5b Mon Sep 17 00:00:00 2001 From: Benoit Blanchon Date: Thu, 6 Nov 2014 13:42:16 +0100 Subject: [PATCH] Added comments --- .../ArduinoJson/Internals/IndentedPrint.hpp | 1 + include/ArduinoJson/Internals/JsonParser.hpp | 3 +++ .../ArduinoJson/Internals/JsonPrintable.hpp | 6 +++++ .../Internals/JsonVariantContent.hpp | 13 +++++++---- .../ArduinoJson/Internals/JsonVariantType.hpp | 23 ++++++++++++------- include/ArduinoJson/Internals/JsonWriter.hpp | 10 ++++++++ 6 files changed, 43 insertions(+), 13 deletions(-) diff --git a/include/ArduinoJson/Internals/IndentedPrint.hpp b/include/ArduinoJson/Internals/IndentedPrint.hpp index a665b5bd..848c9f76 100644 --- a/include/ArduinoJson/Internals/IndentedPrint.hpp +++ b/include/ArduinoJson/Internals/IndentedPrint.hpp @@ -10,6 +10,7 @@ namespace ArduinoJson { namespace Internals { + // Decorator on top of Print to allow indented output. // This class is used by JsonPrintable::prettyPrintTo() but can also be used // for your own purpose, like logging. diff --git a/include/ArduinoJson/Internals/JsonParser.hpp b/include/ArduinoJson/Internals/JsonParser.hpp index 2062f37d..c8ac0b34 100644 --- a/include/ArduinoJson/Internals/JsonParser.hpp +++ b/include/ArduinoJson/Internals/JsonParser.hpp @@ -11,6 +11,9 @@ namespace ArduinoJson { namespace Internals { +// Parse JSON string to create JsonArrays and JsonObjects +// This internal class is not indended to be used directly. +// Instead, use JsonBuffer.parseArray() or .parseObject() class JsonParser { public: JsonParser(JsonBuffer *buffer, char *json, uint8_t nestingLimit) diff --git a/include/ArduinoJson/Internals/JsonPrintable.hpp b/include/ArduinoJson/Internals/JsonPrintable.hpp index 19f34fab..1ed580ff 100644 --- a/include/ArduinoJson/Internals/JsonPrintable.hpp +++ b/include/ArduinoJson/Internals/JsonPrintable.hpp @@ -13,6 +13,10 @@ namespace ArduinoJson { namespace Internals { +// Implements all the overloads of printTo() and prettyPrintTo() +// Caution: this class use a template parameter to avoid virtual methods. +// This is a bit curious but allows to reduce the size of JsonVariant, JsonArray +// and JsonObject. template class JsonPrintable { public: @@ -21,6 +25,7 @@ class JsonPrintable { downcast().writeTo(writer); return writer.bytesWritten(); } + size_t printTo(char *buffer, size_t bufferSize) const { StringBuilder sb(buffer, bufferSize); return printTo(sb); @@ -36,6 +41,7 @@ class JsonPrintable { StringBuilder sb(buffer, bufferSize); return prettyPrintTo(sb); } + size_t prettyPrintTo(Print &print) const { IndentedPrint indentedPrint = IndentedPrint(print); return prettyPrintTo(indentedPrint); diff --git a/include/ArduinoJson/Internals/JsonVariantContent.hpp b/include/ArduinoJson/Internals/JsonVariantContent.hpp index d6966206..3b0e6c6d 100644 --- a/include/ArduinoJson/Internals/JsonVariantContent.hpp +++ b/include/ArduinoJson/Internals/JsonVariantContent.hpp @@ -8,18 +8,21 @@ namespace ArduinoJson { +// Forward declarations class JsonArray; class JsonObject; namespace Internals { +// A union that defines the actual content of a JsonVariant. +// The enum JsonVariantType determines which member is in use. union JsonVariantContent { bool asBoolean; - double asDouble; - long asLong; - const char* asString; - JsonArray* asArray; - JsonObject* asObject; + double asDouble; // asDouble is also used for float + long asLong; // asLong is also used for char, short and int + const char* asString; // asString can be null + JsonArray* asArray; // asArray cannot be null + JsonObject* asObject; // asObject cannot be null }; } } diff --git a/include/ArduinoJson/Internals/JsonVariantType.hpp b/include/ArduinoJson/Internals/JsonVariantType.hpp index 3bf11ad8..cb666ac3 100644 --- a/include/ArduinoJson/Internals/JsonVariantType.hpp +++ b/include/ArduinoJson/Internals/JsonVariantType.hpp @@ -9,18 +9,25 @@ namespace ArduinoJson { namespace Internals { +// Enumerated type to know the current type of a JsonVariant. +// The value determines which member of JsonVariantContent is used. enum JsonVariantType { - JSON_UNDEFINED, - JSON_INVALID, - JSON_ARRAY, - JSON_OBJECT, - JSON_BOOLEAN, - JSON_STRING, - JSON_LONG, + JSON_INVALID, // a special state for JsonVariant::invalid() + JSON_UNDEFINED, // the JsonVariant has not been initialized + JSON_ARRAY, // the JsonVariant stores a pointer to a JsonArray + JSON_OBJECT, // the JsonVariant stores a pointer to a JsonObject + JSON_BOOLEAN, // the JsonVariant stores a bool + JSON_STRING, // the JsonVariant stores a const char* + JSON_LONG, // the JsonVariant stores a long + + // The following values are reserved for double values + // Multiple values are used for double, depending on the number of decimal + // digits that must be printed in the JSON output. + // This little trick allow to save one extra member in JsonVariant JSON_DOUBLE_0_DECIMALS // JSON_DOUBLE_1_DECIMAL // JSON_DOUBLE_2_DECIMALS - // etc. + // ... }; } } diff --git a/include/ArduinoJson/Internals/JsonWriter.hpp b/include/ArduinoJson/Internals/JsonWriter.hpp index b19dbe27..46da6b51 100644 --- a/include/ArduinoJson/Internals/JsonWriter.hpp +++ b/include/ArduinoJson/Internals/JsonWriter.hpp @@ -11,10 +11,20 @@ namespace ArduinoJson { namespace Internals { +// Writes the JSON tokens to a Print implementation +// This class is used by: +// - JsonArray::writeTo() +// - JsonObject::writeTo() +// - JsonVariant::writeTo() +// Its derived by PrettyJsonWriter that overrides some members to add +// indentation. class JsonWriter { public: explicit JsonWriter(Print *sink) : _sink(sink), _length(0) {} + // Returns the number of bytes sent to the Print implementation. + // This is very handy for implementations of printTo() that must return the + // number of bytes written. size_t bytesWritten() { return _length; } void beginArray() { _length += _sink->write('['); }