Merge pull request #533 from toddjordan/document-new-import-scheme

Update documentation for the new way Ember does imports for rsvp

lib/rsvp/all-settled.js

@@ -4,6 +4,11 @@ import {
 } from './enumerator';
 import Promise from './promise';
 
+/**
+@module rsvp
+@public
+**/
+
 class AllSettled extends Enumerator {
   constructor(Constructor, entries, label) {
     super(Constructor, entries, false /* don't abort on reject */, label);
@@ -55,8 +60,9 @@ AllSettled.prototype._setResultAt = setSettledResult;
   ```
 
   @method allSettled
+  @public
   @static
-  @for RSVP
+  @for rsvp
   @param {Array} entries
   @param {String} label - optional string that describes the promise.
   Useful for tooling.

lib/rsvp/all.js

@@ -1,11 +1,12 @@
 import Promise from "./promise";
 
 /**
-  This is a convenient alias for `RSVP.Promise.all`.
+  This is a convenient alias for `Promise.all`.
 
   @method all
+  @public
   @static
-  @for RSVP
+  @for rsvp
   @param {Array} array Array of promises.
   @param {String} label An optional label. This is useful
   for tooling.

lib/rsvp/defer.js

@@ -1,13 +1,13 @@
 import Promise from "./promise";
 
 /**
-  `RSVP.defer` returns an object similar to jQuery's `$.Deferred`.
-  `RSVP.defer` should be used when porting over code reliant on `$.Deferred`'s
-  interface. New code should use the `RSVP.Promise` constructor instead.
+  `defer` returns an object similar to jQuery's `$.Deferred`.
+  `defer` should be used when porting over code reliant on `$.Deferred`'s
+  interface. New code should use the `Promise` constructor instead.
 
-  The object returned from `RSVP.defer` is a plain object with three properties:
+  The object returned from `defer` is a plain object with three properties:
 
-  * promise - an `RSVP.Promise`.
+  * promise - an `Promise`.
   * reject - a function that causes the `promise` property on this object to
     become rejected
   * resolve - a function that causes the `promise` property on this object to
@@ -16,7 +16,7 @@ import Promise from "./promise";
   Example:
 
    ```javascript
-   let deferred = RSVP.defer();
+   let deferred = defer();
 
    deferred.resolve("Success!");
 
@@ -26,8 +26,9 @@ import Promise from "./promise";
    ```
 
   @method defer
+  @public
   @static
-  @for RSVP
+  @for rsvp
   @param {String} label optional string for labeling the promise.
   Useful for tooling.
   @return {Object}

lib/rsvp/events.js

@@ -10,18 +10,22 @@ function callbacksFor(object) {
 }
 
 /**
-  @class RSVP.EventTarget
+  @class EventTarget
+  @for rsvp
+  @public
 */
 export default {
 
   /**
-    `RSVP.EventTarget.mixin` extends an object with EventTarget methods. For
+    `EventTarget.mixin` extends an object with EventTarget methods. For
     Example:
 
     ```javascript
+    import EventTarget from 'rsvp';
+
     let object = {};
 
-    RSVP.EventTarget.mixin(object);
+    EventTarget.mixin(object);
 
     object.on('finished', function(event) {
       // handle event
@@ -33,8 +37,10 @@ export default {
     `EventTarget.mixin` also works with prototypes:
 
     ```javascript
+    import EventTarget from 'rsvp';
+
     let Person = function() {};
-    RSVP.EventTarget.mixin(Person.prototype);
+    EventTarget.mixin(Person.prototype);
 
     let yehuda = new Person();
     let tom = new Person();
@@ -52,7 +58,7 @@ export default {
     ```
 
     @method mixin
-    @for RSVP.EventTarget
+    @for rsvp
     @private
     @param {Object} object object to extend with EventTarget methods
   */
@@ -76,7 +82,7 @@ export default {
     ```
 
     @method on
-    @for RSVP.EventTarget
+    @for EventTarget
     @private
     @param {String} eventName name of the event to listen for
     @param {Function} callback function to be called when the event is triggered.
@@ -129,7 +135,7 @@ export default {
     ```
 
     @method off
-    @for RSVP.EventTarget
+    @for rsvp
     @private
     @param {String} eventName event to stop listening to
     @param {Function} callback optional argument. If given, only the function
@@ -177,7 +183,7 @@ export default {
     ```
 
     @method trigger
-    @for RSVP.EventTarget
+    @for rsvp
     @private
     @param {String} eventName name of the event to be triggered
     @param {*} options optional value to be passed to any event handlers for

lib/rsvp/filter.js

@@ -38,64 +38,68 @@ class FilterEnumerator extends MapEnumerator {
 }
 
 /**
- `RSVP.filter` is similar to JavaScript's native `filter` method.
+ `filter` is similar to JavaScript's native `filter` method.
  `filterFn` is eagerly called meaning that as soon as any promise
-  resolves its value will be passed to `filterFn`. `RSVP.filter` returns
+  resolves its value will be passed to `filterFn`. `filter` returns
   a promise that will become fulfilled with the result of running
   `filterFn` on the values the promises become fulfilled with.
 
   For example:
 
   ```javascript
+  import { filter, resolve } from 'rsvp';
 
-  let promise1 = RSVP.resolve(1);
-  let promise2 = RSVP.resolve(2);
-  let promise3 = RSVP.resolve(3);
+  let promise1 = resolve(1);
+  let promise2 = resolve(2);
+  let promise3 = resolve(3);
 
   let promises = [promise1, promise2, promise3];
 
   let filterFn = function(item){
     return item > 1;
   };
 
-  RSVP.filter(promises, filterFn).then(function(result){
+  filter(promises, filterFn).then(function(result){
     // result is [ 2, 3 ]
   });
   ```
 
-  If any of the `promises` given to `RSVP.filter` are rejected, the first promise
+  If any of the `promises` given to `filter` are rejected, the first promise
   that is rejected will be given as an argument to the returned promise's
   rejection handler. For example:
 
   ```javascript
-  let promise1 = RSVP.resolve(1);
-  let promise2 = RSVP.reject(new Error('2'));
-  let promise3 = RSVP.reject(new Error('3'));
+  import { filter, reject, resolve } from 'rsvp';
+
+  let promise1 = resolve(1);
+  let promise2 = reject(new Error('2'));
+  let promise3 = reject(new Error('3'));
   let promises = [ promise1, promise2, promise3 ];
 
   let filterFn = function(item){
     return item > 1;
   };
 
-  RSVP.filter(promises, filterFn).then(function(array){
+  filter(promises, filterFn).then(function(array){
     // Code here never runs because there are rejected promises!
   }, function(reason) {
     // reason.message === '2'
   });
   ```
 
-  `RSVP.filter` will also wait for any promises returned from `filterFn`.
+  `filter` will also wait for any promises returned from `filterFn`.
   For instance, you may want to fetch a list of users then return a subset
   of those users based on some asynchronous operation:
 
   ```javascript
+  import { filter, resolve } from 'rsvp';
 
   let alice = { name: 'alice' };
   let bob   = { name: 'bob' };
   let users = [ alice, bob ];
 
   let promises = users.map(function(user){
-    return RSVP.resolve(user);
+    return resolve(user);
   });
 
   let filterFn = function(user){
@@ -104,7 +108,7 @@ class FilterEnumerator extends MapEnumerator {
       return privs.can_create_blog_post === true;
     });
   };
-  RSVP.filter(promises, filterFn).then(function(users){
+  filter(promises, filterFn).then(function(users){
     // true, because the server told us only Alice can create a blog post.
     users.length === 1;
     // false, because Alice is the only user present in `users`
@@ -113,8 +117,9 @@ class FilterEnumerator extends MapEnumerator {
   ```
 
   @method filter
+  @public
   @static
-  @for RSVP
+  @for rsvp
   @param {Array} promises
   @param {Function} filterFn - function to be called on each resolved value to
   filter the final results.
@@ -125,13 +130,13 @@ class FilterEnumerator extends MapEnumerator {
 
 export default function filter(promises, filterFn, label) {
   if (typeof filterFn !== 'function') {
-    return Promise.reject(new TypeError("RSVP.filter expects function as a second argument"), label);
+    return Promise.reject(new TypeError("filter expects function as a second argument"), label);
   }
 
   return Promise.resolve(promises, label)
     .then(function(promises) {
       if (!Array.isArray(promises)) {
-        throw new TypeError("RSVP.filter must be called with an array");
+        throw new TypeError("filter must be called with an array");
       }
       return new FilterEnumerator(Promise, promises, filterFn, label).promise;
     });

lib/rsvp/hash-settled.js

@@ -14,11 +14,11 @@ class HashSettled extends PromiseHash {
 HashSettled.prototype._setResultAt = setSettledResult;
 
 /**
-  `RSVP.hashSettled` is similar to `RSVP.allSettled`, but takes an object
+  `hashSettled` is similar to `allSettled`, but takes an object
   instead of an array for its `promises` argument.
 
-  Unlike `RSVP.all` or `RSVP.hash`, which implement a fail-fast method,
-  but like `RSVP.allSettled`, `hashSettled` waits until all the
+  Unlike `all` or `hash`, which implement a fail-fast method,
+  but like `allSettled`, `hashSettled` waits until all the
   constituent promises have returned and then shows you all the results
   with their states and values/reasons. This is useful if you want to
   handle multiple promises' failure states together as a set.
@@ -34,14 +34,16 @@ HashSettled.prototype._setResultAt = setSettledResult;
   Example:
 
   ```javascript
+  import { hashSettled, resolve } from 'rsvp';
+
   let promises = {
-    myPromise: RSVP.Promise.resolve(1),
-    yourPromise: RSVP.Promise.resolve(2),
-    theirPromise: RSVP.Promise.resolve(3),
+    myPromise: resolve(1),
+    yourPromise: resolve(2),
+    theirPromise: resolve(3),
     notAPromise: 4
   };
 
-  RSVP.hashSettled(promises).then(function(hash){
+  hashSettled(promises).then(function(hash){
     // hash here is an object that looks like:
     // {
     //   myPromise: { state: 'fulfilled', value: 1 },
@@ -52,19 +54,21 @@ HashSettled.prototype._setResultAt = setSettledResult;
   });
   ```
 
-  If any of the `promises` given to `RSVP.hash` are rejected, the state will
+  If any of the `promises` given to `hash` are rejected, the state will
   be set to 'rejected' and the reason for rejection provided.
 
   Example:
 
   ```javascript
+  import { hashSettled, reject, resolve } from 'rsvp';
+
   let promises = {
-    myPromise: RSVP.Promise.resolve(1),
-    rejectedPromise: RSVP.Promise.reject(new Error('rejection')),
-    anotherRejectedPromise: RSVP.Promise.reject(new Error('more rejection')),
+    myPromise: resolve(1),
+    rejectedPromise: reject(new Error('rejection')),
+    anotherRejectedPromise: reject(new Error('more rejection')),
   };
 
-  RSVP.hashSettled(promises).then(function(hash){
+  hashSettled(promises).then(function(hash){
     // hash here is an object that looks like:
     // {
     //   myPromise:              { state: 'fulfilled', value: 1 },
@@ -76,24 +80,26 @@ HashSettled.prototype._setResultAt = setSettledResult;
   });
   ```
 
-  An important note: `RSVP.hashSettled` is intended for plain JavaScript objects that
-  are just a set of keys and values. `RSVP.hashSettled` will NOT preserve prototype
+  An important note: `hashSettled` is intended for plain JavaScript objects that
+  are just a set of keys and values. `hashSettled` will NOT preserve prototype
   chains.
 
   Example:
 
   ```javascript
+  import Promise, { hashSettled, resolve } from 'rsvp';
+
   function MyConstructor(){
-    this.example = RSVP.Promise.resolve('Example');
+    this.example = resolve('Example');
   }
 
   MyConstructor.prototype = {
-    protoProperty: RSVP.Promise.resolve('Proto Property')
+    protoProperty: Promise.resolve('Proto Property')
   };
 
   let myObject = new MyConstructor();
 
-  RSVP.hashSettled(myObject).then(function(hash){
+  hashSettled(myObject).then(function(hash){
     // protoProperty will not be present, instead you will just have an
     // object that looks like:
     // {
@@ -106,7 +112,8 @@ HashSettled.prototype._setResultAt = setSettledResult;
   ```
 
   @method hashSettled
-  @for RSVP
+  @public
+  @for rsvp
   @param {Object} object
   @param {String} label optional string that describes the promise.
   Useful for tooling.
@@ -117,7 +124,7 @@ HashSettled.prototype._setResultAt = setSettledResult;
 
 export default function hashSettled(object, label) {
   if (object === null || typeof object !== 'object') {
-    return Promise.reject(new TypeError("RSVP.hashSettled must be called with an object"), label);
+    return Promise.reject(new TypeError("hashSettled must be called with an object"), label);
   }
 
   return new HashSettled(Promise, object, false, label).promise;