Merge pull request #123 from ed7coyne/add-docs

Add javadocs to Arduino API.

Author: ed7coyne

src/FirebaseArduino.h

@@ -20,18 +20,98 @@
 #include "Firebase.h"
 #include "FirebaseObject.h"
 
+/**
+ * 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 
+ * Firebase.h.
+ */
 class FirebaseArduino {
  public:
+  /**
+   * 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 = "");
+
+  /**
+   * 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 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 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.
+   * \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 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 node, and possibly entire tree, located at path.
+   * You should check success() after calling.
+   * \param path The path 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_;

src/FirebaseObject.h

@@ -23,14 +23,49 @@
 #define FIREBASE_JSONBUFFER_SIZE 200
 #endif // FIREBASE_JSONBUFFER_SIZE
 
+/**
+ * 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<const char*> operator[](const char* key);
   JsonObjectSubscript<const String&> operator[](const String& key);
   JsonVariant operator[](JsonObjectKey key) const;