Call out in documentation that requests may only be sent once. (#1536)

* Call out in documentation that requests may only be sent once. Also indicate which methods cause the request to be sent.

* Remove --production flag from browser rake task and ensure Travis is testing node 8.0

.travis.yml

@@ -5,9 +5,10 @@ node_js:
   - "0.12"
   - "4.2"
   - "4.4"
-  - "5.11"
-  - "6.1"
-  - "node"
+  - "5"
+  - "6"
+  - "7"
+  - "8"
 
 before_install:
   - "if [[ `node -v` == v0.8.* ]]; then npm install -g npm || exit 0; fi"

dist-tools/browser-builder.js

@@ -2,7 +2,7 @@
 
 var path = require('path');
 
-var AWS = require('../');
+var AWS = require('../index');
 
 var license = [
   '// AWS SDK for JavaScript v' + AWS.VERSION,

lib/request.js

@@ -86,6 +86,10 @@ fsm.setupStates();
  * request.send();
  * ```
  *
+ * Since registered callbacks may or may not be idempotent, requests should only
+ * be sent once. To perform the same operation multiple times, you will need to
+ * create multiple request objects, each with its own registered callbacks.
+ *
  * ## Removing Default Listeners for Events
  *
  * Request objects are built with default listeners for the various events,
@@ -367,7 +371,7 @@ AWS.Request = inherit({
 
   /**
    * @!method  promise()
-   *   Returns a 'thenable' promise.
+   *   Sends the request and returns a 'thenable' promise.
    *
    *   Two callbacks can be provided to the `then` method on the returned promise.
    *   The first callback will be called if the promise is fulfilled, and the second
@@ -542,8 +546,8 @@ AWS.Request = inherit({
   },
 
   /**
-   * Converts the request object into a readable stream that
-   * can be read from or piped into a writable stream.
+   * Sends the request and converts the request object into a readable stream
+   * that can be read from or piped into a writable stream.
    *
    * @note The data read from a readable stream contains only
    *   the raw HTTP body contents.

tasks/browser.rake

@@ -35,7 +35,7 @@ namespace :browser do
   task :setup_dist_tools do
     unless File.directory?("dist-tools/node_modules")
       Dir.chdir('dist-tools') do
-        sh "npm install --production"
+        sh "npm install"
       end
     end
   end