From a1f64faea4447db0166d4151d791f2b56dd29885 Mon Sep 17 00:00:00 2001 From: Ed Coyne Date: Fri, 6 May 2016 16:25:55 -0700 Subject: [PATCH 1/4] Added comments to arduino api. --- src/FirebaseArduino.h | 78 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/src/FirebaseArduino.h b/src/FirebaseArduino.h index c22b7594..bf304dac 100644 --- a/src/FirebaseArduino.h +++ b/src/FirebaseArduino.h @@ -24,18 +24,96 @@ #define FIREBASE_JSONBUFFER_SIZE 200 #endif // FIREBASE_JSONBUFFER_SIZE +/** + * Gateway class for Arduino clients to interact with the Firebase backend. + * This implementation is designed to follow Arduino best practices and favor + * simplicity over all else. For more complicated usecases and more control + * see the Firebase class in Firebase.h. + */ class FirebaseArduino { public: + /** + * Must be called first. This sets the class up for use. + * \param host Your firebase db server domain name, usually X.firebaseIO.com. + * \param auth Optional authentication for the db, a Secret or Token. + */ void begin(const char* host, const char* auth = ""); + + /** + * Adds the data in value to the list located at path. Equivilent to the + * REST API's POST. + * You should check success() after calling. + * \param path The path inside of your db to the list you wish to update. + * \param value Data that you wish to add to the list. + * \return The child name where the data was written. + */ String push(const String& path, const JsonVariant& value); + + /** + * Writes the data in value to the node located at path Equivilent to the + * REST API's PUT. + * You should check success() after calling. + * \param path The path inside of your db to the node you wish to update. + * \param value Data that you wish to write. + */ void set(const String& path, const JsonVariant& value); + + + /** + * Gets the value located at path. + * You should check success() after calling. + * \param path The path inside of your db of the node you wish to retrieve. + * \return The data located at that path. This may either be a single element + * or it may be a json structure. Will only be populated if success() is true. + */ FirebaseObject get(const char* path); + + /** + * Remove the variable, and possibly entire tree, located at path. + * You should check success() after calling. + * \param path The path inside of your db to the node you wish to remove, + * including all of its children. + */ void remove(const char* path); + + /** + * Starts streaming any changes made to the node located at path, including + * any of its children. + * You should check success() after calling. + * This changes the state of this object. Once this is called you may start + * monitoring available() and calling readEvent() to get new events. + * \param path The path inside of your db to the node you wish to monitor. + */ void stream(const char* path); + + /** + * Checks if there are new events available. This is only meaningful once + * stream() has been called. + * \return If a new event is ready. + */ bool available(); + + /** + * Reads the next event in a stream. This is only meaningful once stream() has + * been called. + * \return Object will have ["type"] that describes the event type, ["path"] + * that describes the effected path and ["data"] that was updated. + */ FirebaseObject readEvent(); + + /** + * \return Whether the last command was successful. + */ bool success(); + + /** + * \return Whether the last command failed. + */ bool failed(); + + /** + * \return Error message from last command if failed() is true. + */ const String& error(); private: String host_; From dba2feef87cb22661d1824084ec28d3dcecc30aa Mon Sep 17 00:00:00 2001 From: Ed Coyne Date: Fri, 6 May 2016 16:38:47 -0700 Subject: [PATCH 2/4] Added comments to FirebaseObject --- src/FirebaseObject.h | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/src/FirebaseObject.h b/src/FirebaseObject.h index a4358328..dd5b09b7 100644 --- a/src/FirebaseObject.h +++ b/src/FirebaseObject.h @@ -21,14 +21,49 @@ #define FIREBASE_JSONBUFFER_SIZE 200 +/** + * Represents value stored in firebase, may be a singular value (leaf node) or + * a tree structure. + */ class FirebaseObject { public: + /** + * Construct from json. + * \param data Json formatted string. + */ FirebaseObject(const String& data); + + /** + * Interpret result as a bool, only applicable if result is a single element + * and not a tree. + */ operator bool(); + + /** + * Interpret result as a int, only applicable if result is a single element + * and not a tree. + */ operator int(); + + /** + * Interpret result as a float, only applicable if result is a single element + * and not a tree. + */ operator float(); + + /** + * Interpret result as a String, only applicable if result is a single element + * and not a tree. + */ operator const String&(); + + /** + * Interpret result as a JsonObject, if the result is a tree use this or the + * operator[] methods below. + */ operator const JsonObject&(); + + //TODO(proppy): Add comments to these. JsonObjectSubscript operator[](const char* key); JsonObjectSubscript operator[](const String& key); JsonVariant operator[](JsonObjectKey key) const; From e482a2f5ad7d51d537b2abf732eb2f03c9214005 Mon Sep 17 00:00:00 2001 From: Ed Coyne Date: Fri, 6 May 2016 16:43:18 -0700 Subject: [PATCH 3/4] Minor comment update --- src/FirebaseArduino.h | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/src/FirebaseArduino.h b/src/FirebaseArduino.h index bf304dac..850b2de3 100644 --- a/src/FirebaseArduino.h +++ b/src/FirebaseArduino.h @@ -27,15 +27,16 @@ /** * Gateway class for Arduino clients to interact with the Firebase backend. * This implementation is designed to follow Arduino best practices and favor - * simplicity over all else. For more complicated usecases and more control - * see the Firebase class in Firebase.h. + * simplicity over all else. + * For more complicated usecases and more control see the Firebase class in + * Firebase.h. */ class FirebaseArduino { public: /** * Must be called first. This sets the class up for use. - * \param host Your firebase db server domain name, usually X.firebaseIO.com. - * \param auth Optional authentication for the db, a Secret or Token. + * \param host Your firebase db domain name, usually X.firebaseIO.com. + * \param auth Optional authentication for the db, a secret or token. */ void begin(const char* host, const char* auth = ""); From 813858175d555cfb1b63f0edbf03ecd769a7c2c8 Mon Sep 17 00:00:00 2001 From: Ed Coyne Date: Wed, 11 May 2016 15:22:40 -0700 Subject: [PATCH 4/4] Comment updates from PR review. --- src/FirebaseArduino.h | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/src/FirebaseArduino.h b/src/FirebaseArduino.h index 850b2de3..a00e1a15 100644 --- a/src/FirebaseArduino.h +++ b/src/FirebaseArduino.h @@ -25,7 +25,7 @@ #endif // FIREBASE_JSONBUFFER_SIZE /** - * Gateway class for Arduino clients to interact with the Firebase backend. + * Main class for Arduino clients to interact with Firebase. * This implementation is designed to follow Arduino best practices and favor * simplicity over all else. * For more complicated usecases and more control see the Firebase class in @@ -34,24 +34,25 @@ class FirebaseArduino { public: /** - * Must be called first. This sets the class up for use. - * \param host Your firebase db domain name, usually X.firebaseIO.com. - * \param auth Optional authentication for the db, a secret or token. + * Must be called first. This initialize the client with the given + * firebase host and credentials. + * \param host Your firebase db host, usually X.firebaseio.com. + * \param auth Optional credentials for the db, a secret or token. */ void begin(const char* host, const char* auth = ""); /** - * Adds the data in value to the list located at path. Equivilent to the - * REST API's POST. + * Writes data to a new child location under the parent at path. + * Equivalent to the REST API's POST. * You should check success() after calling. - * \param path The path inside of your db to the list you wish to update. - * \param value Data that you wish to add to the list. - * \return The child name where the data was written. + * \param path The path inside of your db to the parent object. + * \param value Data that you wish to add under the parent. + * \return The unique child key where the data was written. */ String push(const String& path, const JsonVariant& value); /** - * Writes the data in value to the node located at path Equivilent to the + * Writes the data in value to the node located at path equivalent to the * REST API's PUT. * You should check success() after calling. * \param path The path inside of your db to the node you wish to update. @@ -63,16 +64,16 @@ class FirebaseArduino { /** * Gets the value located at path. * You should check success() after calling. - * \param path The path inside of your db of the node you wish to retrieve. + * \param path The path to the node you wish to retrieve. * \return The data located at that path. This may either be a single element * or it may be a json structure. Will only be populated if success() is true. */ FirebaseObject get(const char* path); /** - * Remove the variable, and possibly entire tree, located at path. + * Remove the node, and possibly entire tree, located at path. * You should check success() after calling. - * \param path The path inside of your db to the node you wish to remove, + * \param path The path to the node you wish to remove, * including all of its children. */ void remove(const char* path);