[FIX] doc errors

bzr revid: xmo@openerp.com-20121116111043-s0xuy1lya3am6tia

3 files changed, 101 insertions, 5 deletions

diff --git a/addons/web/doc/async.rst b/addons/web/doc/async.rst
index 31e6199a6fa..6782fdac029 100644
--- a/addons/web/doc/async.rst
+++ b/addons/web/doc/async.rst
@@ -240,6 +240,103 @@ for instance (to take advantage of :js:func:`when` 's special
 treatment of single-value promises).
 
 
+jQuery.Deferred API
+~~~~~~~~~~~~~~~~~~~
+
+.. js:function:: when(deferreds…)
+
+    :param deferreds: deferred objects to multiplex
+    :returns: a multiplexed deferred
+    :rtype: :js:class:`Deferred`
+
+.. js:class:: Deferred
+
+    .. js:function:: Deferred.then(doneCallback[, failCallback])
+
+        Attaches new callbacks to the resolution or rejection of the
+        deferred object. Callbacks are executed in the order they are
+        attached to the deferred.
+
+        To provide only a failure callback, pass ``null`` as the
+        ``doneCallback``, to provide only a success callback the
+        second argument can just be ignored (and not passed at all).
+
+        Returns a new deferred which resolves to the result of the
+        corresponding callback, if a callback returns a deferred
+        itself that new deferred will be used as the resolution of the
+        chain.
+
+        :param doneCallback: function called when the deferred is resolved
+        :type doneCallback: Function
+        :param failCallback: function called when the deferred is rejected
+        :type failCallback: Function
+        :returns: the deferred object on which it was called
+        :rtype: :js:class:`Deferred`
+
+    .. js:function:: Deferred.done(doneCallback)
+
+        Attaches a new success callback to the deferred, shortcut for
+        ``deferred.then(doneCallback)``.
+
+        This is a jQuery extension to `CommonJS Promises/A`_ providing
+        little value over calling :js:func:`~Deferred.then` directly,
+        it should be avoided.
+
+        :param doneCallback: function called when the deferred is resolved
+        :type doneCallback: Function
+        :returns: the deferred object on which it was called
+        :rtype: :js:class:`Deferred`
+
+    .. js:function:: Deferred.fail(failCallback)
+
+        Attaches a new failure callback to the deferred, shortcut for
+        ``deferred.then(null, failCallback)``.
+
+        A second jQuery extension to `Promises/A <CommonJS
+        Promises/A>`_. Although it provides more value than
+        :js:func:`~Deferred.done`, it still is not much and should be
+        avoided as well.
+
+        :param failCallback: function called when the deferred is rejected
+        :type failCallback: Function
+        :returns: the deferred object on which it was called
+        :rtype: :js:class:`Deferred`
+
+    .. js:function:: Deferred.promise()
+
+        Returns a read-only view of the deferred object, with all
+        mutators (resolve and reject) methods removed.
+
+    .. js:function:: Deferred.resolve(value…)
+
+        Called to resolve a deferred, any value provided will be
+        passed onto the success handlers of the deferred object.
+
+        Resolving a deferred which has already been resolved or
+        rejected has no effect.
+
+    .. js:function:: Deferred.reject(value…)
+
+        Called to reject (fail) a deferred, any value provided will be
+        passed onto the failure handler of the deferred object.
+
+        Rejecting a deferred which has already been resolved or
+        rejected has no effect.
+
+.. [#] or simply calling :js:class:`Deferred` as a function, the
+       result is the same
+
+.. [#] or not-promises, the `CommonJS Promises/B`_ role of
+       :js:func:`when` is to be able to treat values and promises
+       uniformly: :js:func:`when` will pass promises through directly,
+       but non-promise values and objects will be transformed into a
+       resolved promise (resolving themselves with the value itself).
+
+       jQuery's :js:func:`when` keeps this behavior making deferreds
+       easy to build from "static" values, or allowing defensive code
+       where expected promises are wrapped in :js:func:`when` just in
+       case.
+
 .. _promises: http://en.wikipedia.org/wiki/Promise_(programming)
 .. _jQuery's deferred: http://api.jquery.com/category/deferred-object/
 .. _CommonJS Promises/A: http://wiki.commonjs.org/wiki/Promises/A
diff --git a/addons/web/doc/index.rst b/addons/web/doc/index.rst
index d196083c6d1..06534c50903 100644
--- a/addons/web/doc/index.rst
+++ b/addons/web/doc/index.rst
@@ -14,6 +14,8 @@ Contents:
     presentation
     async
 
+    testing
+
     widget
     qweb
     rpc
@@ -24,9 +26,6 @@ Contents:
 
     changelog-7.0
 
-
-    testing
-
 Indices and tables
 ==================
 
diff --git a/addons/web/doc/testing.rst b/addons/web/doc/testing.rst
index fea6f8e2616..600d379aa02 100644
--- a/addons/web/doc/testing.rst
+++ b/addons/web/doc/testing.rst
@@ -70,7 +70,7 @@ module. OpenERP tests live in a :js:func:`~openerp.testing.section`,
 which is itself part of a module. The first argument to a section is
 the name of the section, the second one is the section body.
 
-:js:func:`~openerp.testing.test`, provided by the
+:js:func:`test <openerp.testing.case>`, provided by the
 :js:func:`~openerp.testing.section` to the callback, is used to
 register a given test case which will be run whenever the test runner
 actually does its job. OpenERP Web test case use standard `QUnit
@@ -196,7 +196,7 @@ strongly discouraged during tests. But DOM access is still needed to
 e.g. fully initialize :js:class:`widgets <~openerp.web.Widget>` before
 testing them.
 
-Thus, test cases get a DOM scratchpad as its second positional
+Thus, a test case gets a DOM scratchpad as its second positional
 parameter, in a jQuery instance. That scratchpad is fully cleaned up
 before each test, and as long as it doesn't do anything outside the
 scratchpad your code can do whatever it wants::