From a577ee12a0fccbd0f57c3087cfff86a9672ef271 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=A9ry=20Debongnie?= <ged@odoo.com>
Date: Thu, 19 Apr 2018 10:33:21 +0200
Subject: [PATCH] [DOC] web: add documentation on notification system

Also, fix a few errors in the js docstring
---
 .../src/js/services/notification_service.js   |  4 +-
 .../static/src/js/views/basic/basic_model.js  |  2 +-
 doc/reference/javascript_reference.rst        | 78 +++++++++++++++++++
 3 files changed, 81 insertions(+), 3 deletions(-)

diff --git a/addons/web/static/src/js/services/notification_service.js b/addons/web/static/src/js/services/notification_service.js
index 7d6ad473fe4..bbeeca51bb8 100644
--- a/addons/web/static/src/js/services/notification_service.js
+++ b/addons/web/static/src/js/services/notification_service.js
@@ -71,12 +71,12 @@ var NotificationService = AbstractService.extend({
      * @param {string} [params.buttons[0].icon] font-awsome className or image src
      * @returns {Number} notification id
      */
-    notify: function (options) {
+    notify: function (params) {
         if (!this.$el) {
             this.$el = $('<div class="o_notification_manager"/>');
             this.$el.prependTo('body');
         }
-        var notification = this.notifications[++id] = new Notification(this, options);
+        var notification = this.notifications[++id] = new Notification(this, params);
         notification.appendTo(this.$el);
         return id;
     },
diff --git a/addons/web/static/src/js/views/basic/basic_model.js b/addons/web/static/src/js/views/basic/basic_model.js
index e86d7dba8f7..45d698cd75b 100644
--- a/addons/web/static/src/js/views/basic/basic_model.js
+++ b/addons/web/static/src/js/views/basic/basic_model.js
@@ -948,7 +948,7 @@ var BasicModel = AbstractModel.extend({
      * - call the /create or /write method according to the record status
      * - After that, it has to reload all data, in case something changed, server side.
      *
-     * @param {string} record_id local resource
+     * @param {string} recordID local resource
      * @param {Object} [options]
      * @param {boolean} [options.reload=true] if true, data will be reloaded
      * @param {boolean} [options.savePoint=false] if true, the record will only
diff --git a/doc/reference/javascript_reference.rst b/doc/reference/javascript_reference.rst
index 1194296251a..0e9c89f611c 100644
--- a/doc/reference/javascript_reference.rst
+++ b/doc/reference/javascript_reference.rst
@@ -1142,6 +1142,84 @@ may need to directly call a controller (available on some route).
         params: { some: kwargs},
     });
 
+Notifications
+==============
+
+The Odoo framework has a standard way to communicate various informations to the
+user: notifications, which are displayed on the top right of the user interface.
+
+There are two types of notifications:
+
+- *notification*: useful to display some feedback.  For example, whenever a user
+  unsubscribed to a channel.
+
+- *warning*: useful to display some important/urgent information.  Typically
+  most kind of (recoverable) errors in the system.
+
+Also, notifications can be used to ask a question to the user without disturbing
+its workflow.  Imagine a phone call received through VOIP: a sticky notification
+could be displayed with two buttons *Accept* and *Decline*.
+
+Notification system
+-------------------
+
+The notification system in Odoo is designed with the following components:
+
+- a *Notification* widget: this is a simple widget that is meant to be created
+  and displayed with the desired information
+
+- a *NotificationService*: a service whose responsability is to create and
+  destroy notifications whenever a request is done (with a custom_event). Note
+  that the web client is a service provider.
+
+- two helper functions in *ServiceMixin*: *do_notify* and *do_warn*
+
+
+Displaying a notification
+-------------------------
+The most common way to display a notification is by using two methods that come
+from the *ServiceMixin*:
+
+- *do_notify(title, message, sticky, className)*:
+    Display a notification of type *notification*.
+
+    - *title*: string. This will be displayed on the top as a title
+
+    - *message*: string, the content of the notification
+
+    - *sticky*: boolean, optional. If true, the notification will stay until the
+      user dismisses it.  Otherwise, the notification will be automatically
+      closed after a short delay.
+
+    - *className*: string, optional.  This is a css class name that will be
+      automatically added to the notification.  This could be useful for styling
+      purpose, even though its use is discouraged.
+
+- *do_warn(title, message, sticky, className)*:
+    Display a notification of type *warning*.
+
+    - *title*: string. This will be displayed on the top as a title
+
+    - *message*: string, the content of the notification
+
+    - *sticky*: boolean, optional. If true, the notification will stay until the
+      user dismisses it.  Otherwise, the notification will be automatically
+      closed after a short delay.
+
+    - *className*: string, optional.  This is a css class name that will be
+      automatically added to the notification.  This could be useful for styling
+      purpose, even though its use is discouraged.
+
+Here are two examples on how to use these methods:
+
+.. code-block:: javascript
+
+    // note that we call _t on the text to make sure it is properly translated.
+    this.do_notify(_t("Success"), _t("Your signature request has been sent."));
+
+    this.do_warn(_t("Error"), _t("Filter name is required."));
+
+
 
 Translation management
 ======================