Document object handlers in C++

Document changes in [firmware PR particle-iot#534](particle-iot/device-os#534)

Please tag with milestone `firmware-0.4.4`

src/content/reference/firmware.md

@@ -126,55 +126,39 @@ int brewCoffee(String command)
 
 ---
 
-The API request will be routed to the device and will run your brew function. The response will have a return_value key containing the integer returned by brew.
-
-```json
-COMPLEMENTARY API CALL
-POST /v1/devices/{DEVICE_ID}/{FUNCTION}
-
-# EXAMPLE REQUEST
-curl https://api.particle.io/v1/devices/0123456789abcdef/brew \
-     -d access_token=123412341234 \
-     -d "args=coffee"
-```
-
----
-
-To expose a method on an object through the Cloud, use a C++ function wrapper.
-For more details, research `std::function`.
+You can expose a method on a C++ object to the Cloud.
 
 ```C++
 // EXAMPLE USAGE WITH C++ OBJECT
 
 class CoffeeMaker {
   public:
-    int brew(String command);
-    void registerCloud();
-};
+    CoffeeMaker() {
+      Spark.function("brew", &CoffeeMaker::brew, this);
+    }
 
-int CoffeeMaker::brew(String command) {
-  // do stuff
-  return 1;
-}
+    int brew(String command) {
+      // do stuff
+      return 1;
+    }
+};
 
-void CoffeeMaker::registerCloud() {
-  // create a function wrapper to call brew on this instance of CoffeeMaker
-  // auto tells the compiler to determine the function wrapper type automatically
-  // std::placeholders::_1 is necessary because brew takes 1 argument
-  auto brewHandler = std::bind(&CoffeeMaker::brew, this, std::placeholders::_1);
+CoffeeMaker myCoffeeMaker;
+// nothing else needed in setup() or loop()
+```
 
-  Spark.function("brew", brewHandler);
-}
+---
 
-CoffeeMaker myCoffeeMaker;
+The API request will be routed to the device and will run your brew function. The response will have a return_value key containing the integer returned by brew.
 
-void setup() {
-  myCoffeeMaker.registerCloud();
-}
+```json
+COMPLEMENTARY API CALL
+POST /v1/devices/{DEVICE_ID}/{FUNCTION}
 
-void loop() {
-  // this loops forever
-}
+# EXAMPLE REQUEST
+curl https://api.particle.io/v1/devices/0123456789abcdef/brew \
+     -d access_token=123412341234 \
+     -d "args=coffee"
 ```
 
 ### Spark.publish()
@@ -334,6 +318,25 @@ Spark.subscribe("motion/front-door", motionHandler, "55ff70064989495339432587");
 
 ---
 
+You can register a method in a C++ object as a subscription handler.
+
+```cpp
+class Subscriber {
+  public:
+    void subscribe() {
+      Particle.subscribe("some_event", &Subscriber::handler, this);
+    }
+    void handler(const char *eventName, const char *data) {
+      Serial.println(data);
+    }
+};
+
+Subscriber mySubscriber;
+// nothing else needed in setup() or loop()
+```
+
+---
+
 A subscription works like a prefix filter.  If you subscribe to "foo", you will receive any event whose name begins with "foo", including "foo", "fool", "foobar", and "food/indian/sweet-curry-beans".
 
 Received events will be passed to a handler function similar to `Spark.function()`.
@@ -2931,6 +2934,25 @@ void blink()
 }
 ```
 
+You can attach a method in a C++ object as an interrupt handler.
+
+```cpp
+class Robot {
+  public:
+    Robot() {
+      attachInterrupt(D2, &Robot::handler, this, CHANGE);
+    }
+    void handler() {
+      // do something on interrupt
+    }
+};
+
+Robot myRobot;
+// nothing else needed in setup() or loop()
+```
+
+---
+
 External interrupts are supported on the following pins:
 
 - Core: D0, D1, D2, D3, D4, A0, A1, A3, A4, A5, A6, A7