[IMP] minor doc updates

bzr revid: al@openerp.com-20121110214755-4x7skj4o2g2icx4l

addons/web/doc/async.rst

@@ -1,6 +1,9 @@
 Asynchronous Operations
 =======================
 
+This documentation is outdated as then() is now pipe. Please never copy api
+from other libraries just link to it.
+
 As a language (and runtime), javascript is fundamentally
 single-threaded. This means any blocking request or computation will
 blocks the whole page (and, in older browsers, the software itself
@@ -26,8 +29,7 @@ Deferreds
 ---------
 
 Deferreds are a form of `promises`_. OpenERP Web currently uses
-`jQuery's deferred`_, but any `CommonJS Promises/A`_ implementation
-should work.
+`jQuery's deferred`_.
 
 The core idea of deferreds is that potentially asynchronous methods
 will return a :js:class:`Deferred` object instead of an arbitrary
@@ -44,9 +46,8 @@ directly to asynchronous methods is the ability to :ref:`compose them
 Using deferreds
 ~~~~~~~~~~~~~~~
 
-`CommonJS Promises/A`_ deferreds have only one method of importance:
-:js:func:`Deferred.then`. This method is used to attach new callbacks
-to the deferred object.
+deferreds have only one method of importance: :js:func:`Deferred.then`. This
+method is used to attach new callbacks to the deferred object.
 
 * the first parameter attaches a success callback, called when the
   deferred object is successfully resolved and provided with the
@@ -248,103 +249,6 @@ promise-based APIs, in order to filter their resolution value counts
 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).
-
-        :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.
-
-    .. js:function:: Deferred.pipe(doneFilter[, failFilter])
-
-        Filters the result of a deferred, able to transform a success
-        into failure and a failure into success, or to delay
-        resolution further.
-
-.. [#] 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/

addons/web/doc/changelog-7.0.rst

@@ -15,7 +15,7 @@ DataSet -> Model
 ----------------
 
 The 6.1 ``DataSet`` API has been deprecated in favor of the smaller
-and more orthogonal :doc:`Model </rpc>` API, which more closely
+and more orthogonal :doc:`Model </dev_rpc>` API, which more closely
 matches the API in OpenERP Web's Python side and in OpenObject addons
 and removes most stateful behavior of DataSet.
 

addons/web/doc/dev_client_action.rst

@@ -1,7 +1,7 @@
 .. highlight:: javascript
 
-Creating a new client action
-============================
+Client actions
+==============
 
 Client actions are the client-side version of OpenERP's "Server
 Actions": instead of allowing for semi-arbitrary code to be executed

addons/web/doc/dev_qweb.rst

@@ -1,6 +1,6 @@
 
-QWeb Cookbook
-=============
+QWeb
+====
 
 QWeb is the template engine used by the OpenERP Web Client. It is a home made engine create by OpenERP developers. There are a few things to note about it:
 

addons/web/doc/dev_widget.rst

@@ -1,5 +1,5 @@
-User Interaction: Widget
-========================
+Widget
+======
 
 This is the base class for all visual components. It corresponds to an MVC
 view. It provides a number of services to handle a section of a page:

addons/web/doc/index.rst

@@ -12,20 +12,19 @@ Contents:
     :maxdepth: 1
 
     presentation
+    async
+
+    dev_rpc
+    dev_widget
+    dev_qweb
+    dev_client_action
+
+    internal_form
+    internal_list
+    internal_search
 
     changelog-7.0
 
-    async
-    rpc
-
-    widget
-    qweb
-    search-view
-
-    list-view
-    form-notes
-
-    guides/client-action
 
 Indices and tables
 ==================

addons/web/doc/internal_list.rst

@@ -451,7 +451,7 @@ formview, delegating instead to its
         created.
 
         The result should be a valid form view, see :doc:`Form Notes
-        <form-notes>` for various peculiarities of the form view
+        <internal_form>` for various peculiarities of the form view
         format.
 
         :param editor: editor object asking for the view

addons/web/doc/presentation.rst

@@ -7,17 +7,17 @@ Prerequisites
 
 Prerequisites to code addons for the OpenERP Web Client:
 
-- Html
-- Css
-- Javascript
+- HTML5
+- CSS
+- Javascript (Ecmascript 5)
 - jQuery
 
 Once you know all this, that's only the beginning. Most usages of Javascript/jQuery are small hacks to make a web page nicer. The OpenERP Client Web is different: it's a web application, not a web site. It doesn't have multiple pages generated by a server side code. Only one unique empty page is loaded and all the html is generated by Javascript code, the page is never reloaded. If you never developed that kind of application you still have lot of good practices to learn.
 
-Recommendations
----------------
+Generic Guidelines
+------------------
 
-First, here are the 5 golden rules when you create web 2.0 applications:
+First, here are some generic recommandations about web 2.0 applications:
 
 * **Do not use ids**. Html ids are evil, the key anti-feature that makes your components non-reusable. You want to identify a dom part? Save a jQuery object over that dom element. If you really need to use ids, use _.uniqueId(), but 99% of the time you don't need to, classes are sufficient.
 * **Do not use predictable css class names** like "content" or "navigation", ten other developers will have the same idea than you and there will be clashes. A simple way to avoid this is to use prefixes. For example, if you need a css class for the button named "new" that is contained in the form view which is itself contained in the OpenERP application, name it "oe-form-view-new-button".
@@ -25,12 +25,18 @@ First, here are the 5 golden rules when you create web 2.0 applications:
 * As a general advice, **Never assume you own the page**. When you create a component, it is never unique and is always surrounded by a bunch of crazy html. You have to do with it.
 * **Learn how to use jQuery's deferreds** [1]_. That concept may seem over-complicated, but the experience tell us that it is nearly impossible to create big-size javascript applications without that.
 
+OpenERP guidelines
+------------------
 More recommendations related to the specific case of the OpenERP Web Client:
 
-* Your components should inherit from the *Widget* class.
+* The code should conform to EcmasScript 5 without the "use strict" mode as we support IE9.
+
+* Your components should inherit from the *Widget* class. And use *Widget* 's methods (*appendTo*, *replace*,...) to insert your component and its content into the dom.
+
 * Use QWeb templates for html rendering.
-* Use *Widget* 's methods (*appendTo*, *replace*,...) to insert your component and its content into the dom.
+
 * All css classes should have the prefix *oe-* .
+
 * Functions that call rpc() should return a deferred, even if it calls it indirectly. So a function that calls a function that calls a function that calls rpc() should return a deferred too.
 
 .. [1] http://api.jquery.com/category/deferred-object/