Permalink
Browse files

Add deprecation notes to code, docs, and README. Update changelog. Cl…

…ose #76
  • Loading branch information...
1 parent d527c5e commit 25329b0254968e8a9e035b7aa90af50c230401bd @briancavalier briancavalier committed Nov 29, 2012
Showing with 9 additions and 25 deletions.
  1. +5 −22 README.md
  2. +3 −2 docs/api.md
  3. +1 −1 when.js
View
@@ -8,11 +8,12 @@ It passes the [Promises/A Test Suite](https://github.com/domenic/promise-tests),
### 1.7.0
-* `promise.yield(promiseOrValue)` convenience API for substituting a new value into a promise chain.
-* `promise.spread(variadicFunction)` convenience API for registering a fulfill handler that accepts variadic arguments.
+* **DEPRECATED:** `deferred.then` [is deprecated](when/blob/master/docs/api.md#deferred) and will be removed in an upcoming release. Use `deferred.promise.then` instead.
+* [promise.yield](when/blob/master/docs/api.md#yield)(promiseOrValue) convenience API for substituting a new value into a promise chain.
+* [promise.spread](when/blob/master/docs/api.md#spread)(variadicFunction) convenience API for registering a fulfill handler that accepts variadic arguments.
* Doc improvements:
- * when() and promise.then() have more info about callbacks and chaining behavior.
- * More info and clarifications about the roles of Deferred and Resolver
+ * [when()](when/blob/master/docs/api.md#when) and [promise.then()](when/blob/master/docs/api.md#main-promise-api) have more info about callbacks and chaining behavior.
+ * More info and clarifications about the roles of [Deferred](when/blob/master/docs/api.md#deferred) and [Resolver](when/blob/master/docs/api.md#resolver)
* Several minor clarifications for various APIs
* Internal improvements to assimilation and interoperability with other promise implementations.
@@ -29,24 +30,6 @@ It passes the [Promises/A Test Suite](https://github.com/domenic/promise-tests),
* **IMPORTANT:** Continue to treat promises as if they are frozen, since `freeze()` will be reintroduced once v8 performance improves.
* [when/debug](https://github.com/cujojs/when/wiki/when-debug) now allows setting global a debugging callback for rejected promises.
-### 1.5.2
-
-* Integrate @domenic's [Promises/A Test Suite](https://github.com/domenic/promise-tests). Runs via `npm test`.
-* No functional change
-
-### 1.5.1
-
-* Performance optimization for [when.defer](when/blob/master/docs/api.md#whendefer), up to 1.5x in some cases.
-* [when/debug](https://github.com/cujojs/when/wiki/when-debug) can now log exceptions and rejections in deeper promise chains, in some cases, even when the promises involved aren't when.js promises.
-
-### 1.5.0
-
-* New task execution and concurrency management: [when/sequence](when/blob/master/docs/api.md#whensequence), [when/pipeline](when/blob/master/docs/api.md#whenpipeline), and [when/parallel](when/blob/master/docs/api.md#whenparallel).
-* Performance optimizations for [when.all](when/blob/master/docs/api.md#whenall) and [when.map](when/blob/master/docs/api.md#whenmap), up to 2x in some cases.
-* Options for disabling [paranoid mode](when/blob/master/docs/api.md#paranoid-mode) that provides a significant performance gain in v8 (e.g. Node and Chrome). See this [v8 performance problem with Object.freeze](http://stackoverflow.com/questions/8435080/any-performance-benefit-to-locking-down-javascript-objects) for more info.
-* **Important:** `deferred` and `deferred.resolver` no longer throw when resolved/rejected multiple times. They will return silently as if the they had succeeded. This prevents parties to whom *only* the `resolver` has been given from using `try/catch` to determine the state of the associated promise.
- * For debugging, you can use the [when/debug](https://github.com/cujojs/when/wiki/when-debug) module, which will still throw when a deferred is resolved/rejected multiple times.
-
[Full Changelog](https://github.com/cujojs/when/wiki/Changelog)
# Docs & Examples
View
@@ -87,7 +87,9 @@ var promise = deferred.promise;
var resolver = deferred.resolver;
```
-**Note:** Although a deferred has the full `promise` + `resolver` API, this should used *for convenience only, by the creator of the deferred*. Only the `promise` and `resolver` should be given to consumers and producers.
+**DEPRECATED:** Note that `deferred.then` [is deprecated](https://github.com/cujojs/when/issues/76) and [will be removed](https://github.com/cujojs/when/issues/44) in an upcoming release.
+
+**Note:** Although a deferred has the full `resolver` API, this should used *for convenience only, by the creator of the deferred*. Only the `resolver` should be given to consumers and producers.
```js
deferred.resolve(promiseOrValue);
@@ -96,7 +98,6 @@ deferred.progress(update);
// NOTE: deferred.then is DEPRECATED, use deferred.promise.then
deferred.then(onFulfilled, onRejected, onProgress);
-
```
## Resolver
View
@@ -245,7 +245,7 @@ define(function () {
* @name Deferred
*/
deferred = {
- then: then,
+ then: then, // DEPRECATED: use deferred.promise.then
resolve: promiseResolve,
reject: promiseReject,
// TODO: Consider renaming progress() to notify()

0 comments on commit 25329b0

Please sign in to comment.