Document AWSRequest.send() and update examples to use send()

lib/promise.js

@@ -17,12 +17,12 @@ var AWS = require('./core');
 var inherit = AWS.util.inherit;
 
 /**
- * == Asynchronous Promise Objects
+ * == Asynchronous Requests
  *
- * All requests made through the SDK are asynchronous and use an
- * event-based promise callback interface. Each service method
- * that kicks off a request returns an +AWS.AWSRequest+ promise
- * object that you can use to register callbacks.
+ * All requests made through the SDK are asynchronous and use a
+ * callback interface. Each service method that kicks off a request
+ * returns an +AWS.AWSRequest+ object that you can use to register
+ * callbacks.
  *
  * For example, the following service method returns the request
  * object as "request", which can be used to register callbacks:
@@ -35,6 +35,11 @@ var inherit = AWS.util.inherit;
  *     console.log(resp.data);
  *   });
  *
+ * When a request is ready to be sent, the {send} method should
+ * be called:
+ *
+ *   request.send();
+ *
  * == Multiple Callbacks and Chaining
  *
  * You can register multiple callbacks on any request object. The
@@ -51,7 +56,8 @@ var inherit = AWS.util.inherit;
  *     }).
  *     always(function(response) {
  *       console.log("Always!");
- *     });
+ *     }).
+ *     send();
  *
  * The above example will print either "Success! Always!", or "Error! Always!",
  * depending on whether the request succeeded or not.
@@ -68,7 +74,7 @@ var inherit = AWS.util.inherit;
  *   var myContext = new Object();
  *   request.always(function(response) {
  *     console.log(this === myContext);
- *   }, {bind: myContext});
+ *   }, {bind: myContext}).send();
  *
  * The above callback will print +true+ when the callback function is executed.
  *
@@ -88,10 +94,26 @@ AWS.AWSRequest = inherit({
     this.callbacks = { data: [], done: [], fail: [], always: [] };
   },
 
+  /**
+   * @!group Sending a Request
+   */
+
+  /**
+   * Initiates sending of the given request object.
+   *
+   * @example Sending a request
+   *   request = s3.client.putObject({Bucket: 'bucket', Key: 'key'});
+   *   request.done(function(resp) { ... }); // register a callback
+   *   request.send();
+   */
   send: function send() {
     new AWS.RequestHandler(this).makeRequest();
   },
 
+  /**
+   * @!group Registering Callbacks
+   */
+
   /**
    * This event is used to stream response data from the
    * service packet-by-packet. This event is mostly used for large responses,
@@ -102,7 +124,7 @@ AWS.AWSRequest = inherit({
    *
    *   s3.client.getObject({Bucket: b, Key: k}).data(function(resp) {
    *     console.log(resp.data);
-   *   });
+   *   }).send();
    *
    * Prints:
    *
@@ -139,7 +161,7 @@ AWS.AWSRequest = inherit({
    *
    *   s3.client.listBuckets().done(function(response) {
    *     console.log(response.data);
-   *   });
+   *   }).send();
    *
    * Prints:
    *
@@ -178,7 +200,7 @@ AWS.AWSRequest = inherit({
    *   s3.config.credentials.accessKeyId = 'invalid';
    *   s3.client.listBuckets().fail(function(response) {
    *     console.log(response.error);
-   *   });
+   *   }).send();
    *
    * Prints:
    *
@@ -217,7 +239,7 @@ AWS.AWSRequest = inherit({
    *     } else {
    *       // we can use response.data here
    *     }
-   *   });
+   *   }).send();
    *
    * @option options bind [Object] (response object) an object to bind
    *   the callback function to. Defaults to the response object.