Added comments to the code

Author: mirkokurt

src/ArduinoCloudProperty.cpp

@@ -152,14 +152,18 @@ void ArduinoCloudProperty::appendAttributeReal(String value, String attributeNam
 
 void ArduinoCloudProperty::appendAttributeName(String attributeName, std::function<void (CborEncoder& mapEncoder)>appendValue, CborEncoder *encoder) {
   if (attributeName != "") {
+    // when the attribute name string is not empty, the attribute identifier is incremented in order to be encoded in the message if the _lightPayload flag is set
     _attributeIdentifier++;
   }
   CborEncoder mapEncoder;
   cbor_encoder_create_map(encoder, &mapEncoder, 2);
   cbor_encode_int(&mapEncoder, static_cast<int>(CborIntegerMapKey::Name));
 
+  // if _lightPayload is true, the property and attribute identifiers will be encoded instead of the property name
   if (_lightPayload) {
+    // the most significant byte of the identifier to be encoded represent the property identifier
     int completeIdentifier = _attributeIdentifier * 256;
+    // the least significant byte of the identifier to be encoded represent the attribute identifier
     completeIdentifier += _identifier;
     cbor_encode_int(&mapEncoder, completeIdentifier);
   } else {
@@ -211,12 +215,14 @@ void ArduinoCloudProperty::setAttributeReal(String attributeName, std::function<
     CborMapData *map = _map_data_list->get(i);
     if (map != nullptr) {
       if (map->light_payload.isSet() && map->light_payload.get()) {
+        // if a light payload is detected, the attribute identifier is retrieved from the cbor map and the corresponding attribute is updated
         int attid = map->attribute_identifier.get();
         if (attid == _attributeIdentifier) {
           setValue(map);
           break;
         }
       } else {
+        // if a normal payload is detected, the name of the attribute to be updated is extracted directly from the cbor map
         String an = map->attribute_name.get();
         if (an == attributeName) {
           setValue(map);

src/ArduinoCloudThing.cpp

@@ -328,6 +328,7 @@ ArduinoCloudThing::MapParserState ArduinoCloudThing::handle_Name(CborValue * val
   MapParserState next_state = MapParserState::Error;
 
   if (cbor_value_is_text_string(value_iter)) {
+    // if the value in the cbor message is a string, it corresponds to the name of the property to be updated (int the form [property_name]:[attribute_name])
     char * val      = nullptr;
     size_t val_size = 0;
     if (cbor_value_dup_text_string(value_iter, &val, &val_size, value_iter) == CborNoError) {
@@ -343,6 +344,7 @@ ArduinoCloudThing::MapParserState ArduinoCloudThing::handle_Name(CborValue * val
       next_state = MapParserState::MapKey;
     }
   } else if (cbor_value_is_integer(value_iter)) {
+    // if the value in the cbor message is an integer, a light payload has been used and an integer identifier should be decode in order to retrieve the corresponding property and attribute name to be updated
     int val = 0;
     if (cbor_value_get_int(value_iter, &val) == CborNoError) {
       map_data->light_payload.set(true);

src/ArduinoCloudThing.h

@@ -77,10 +77,11 @@ class ArduinoCloudThing {
     ArduinoCloudThing();
 
     void begin();
-
+    //if propertyIdentifier is different from -1, an integer identifier is associated to the added property to be use instead of the property name when the parameter lightPayload is true in the encode method
     ArduinoCloudProperty   & addPropertyReal(ArduinoCloudProperty   & property, String const & name, Permission const permission, int propertyIdentifier = -1);
 
     /* encode return > 0 if a property has changed and encodes the changed properties in CBOR format into the provided buffer */
+    /* if lightPayload is true the integer identifier of the property will be encoded in the message instead of the property name in order to reduce the size of the message payload*/
     int encode(uint8_t * data, size_t const size, bool lightPayload = false);
     /* decode a CBOR payload received from the cloud */
     void decode(uint8_t const * const payload, size_t const length, bool isSyncMessage = false);
@@ -142,6 +143,7 @@ class ArduinoCloudThing {
       if (propertyIdentifier != -1) {
         property_obj->setIdentifier(propertyIdentifier);
       } else {
+        // if property identifier is -1, an incremental value will be assigned as identifier.
         property_obj->setIdentifier(_numProperties);
       }
       _property_list.add(property_obj);

test/src/test_decode.cpp

@@ -51,11 +51,13 @@ SCENARIO("Arduino Cloud Properties are decoded", "[ArduinoCloudThing::decode]")
   /************************************************************************************/
 
   WHEN("A boolean property is changed via CBOR message - light payload") {
+    /*An integer identifier has been encoded instead of the name of the property in order to have a shorter payload*/
     GIVEN("CloudProtocol::V2") {
       ArduinoCloudThing thing;
       thing.begin();
 
       CloudBool test = true;
+      /*The property is added with identifier 1 that will be used instead of the string "test" as property identifier*/
       thing.addPropertyReal(test, "test", Permission::ReadWrite, 1);
 
       /* [{0: 1, 4: false}] = 81 A2 00 01 04 F4 */
@@ -186,12 +188,14 @@ SCENARIO("Arduino Cloud Properties are decoded", "[ArduinoCloudThing::decode]")
   /************************************************************************************/
 
   WHEN("A Color property is changed via CBOR message - light payload") {
+    /*An integer identifier has been encoded instead of the name of the property in order to have a shorter payload*/
     GIVEN("CloudProtocol::V2") {
       ArduinoCloudThing thing;
       thing.begin();
 
       CloudColor color_test = CloudColor(0.0, 0.0, 0.0);
 
+      /*The property is added with identifier 1 that will be used instead of the string "test" as property identifier*/
       thing.addPropertyReal(color_test, "test", Permission::ReadWrite, 1);
 
       /* [{0: 257, 2: 2.0},{0: 513, 2: 2.0},{0: 769, 2: 2.0}] = 83 A2 00 19 01 01 02 FA 40 00 00 00 A2 00 19 02 01 02 FA 40 00 00 00 A2 00 19 03 01 02 FA 40 00 00 00 */

test/src/test_encode.cpp

@@ -41,12 +41,14 @@ SCENARIO("Arduino Cloud Properties are encoded", "[ArduinoCloudThing::encode]")
   /************************************************************************************/
 
   WHEN("A 'bool' property is added - light payload") {
+    /*An integer identifier must be instead of the name of the property in order to have a shorter payload*/
     GIVEN("CloudProtocol::V2") {
       ArduinoCloudThing thing;
       thing.begin();
       encode(thing);
 
       CloudBool test = true;
+      /*The property is added with identifier 1 that will be used instead of the string "test" as property identifier*/
       thing.addPropertyReal(test, "test", Permission::ReadWrite, 1);
 
       /* [{0: 1, 4: true}] = 9F A2 00 01 04 F5 FF*/
@@ -150,12 +152,14 @@ SCENARIO("Arduino Cloud Properties are encoded", "[ArduinoCloudThing::encode]")
   /************************************************************************************/
 
   WHEN("A 'Color' property is added - light payload") {
+    /*An integer identifier must be encoded instead of the name of the property in order to have a shorter payload*/
     GIVEN("CloudProtocol::V2") {
       ArduinoCloudThing thing;
       thing.begin();
       encode(thing);
 
       CloudColor color_test = CloudColor(2.0, 2.0, 2.0);
+      /*The property is added with identifier 1 that will be used instead of the string "name" as property identifier */
       thing.addPropertyReal(color_test, "test", Permission::ReadWrite, 1);
 
       /* [{0: 257, 2: 2.0},{0: 513, 2: 2.0},{0: 769, 2: 2.0}] = 9F A2 00 19 01 01 02 FA 40 00 00 00 A2 00 19 02 01 02 FA 40 00 00 00 A2 00 19 03 01 02 FA 40 00 00 00 FF*/