[IMP] developer: reorder and improve notification service

closes odoo/documentation#1265

Signed-off-by: Victor Feyens (vfe) <vfe@odoo.com>

content/developer/reference/frontend/services.rst

@@ -118,6 +118,8 @@ Reference List
      - Short Description
    * - :ref:`cookie <services/cookie>`
      - read or modify cookies
+   * - :ref:`notification <services/notification>`
+     - display notifications
    * - :ref:`rpc <services/rpc>`
      - send requests to the server
    * - :ref:`title <services/title>`
@@ -163,6 +165,120 @@ API
 
     Deletes the cookie `name`.
 
+.. _services/notification:
+
+Notification service
+--------------------
+
+Overview
+~~~~~~~~
+
+* Technical name: `notification`
+* Dependencies: None
+
+The `notification` service allows to display notifications on the screen.
+  
+.. code-block:: javascript
+
+  const notificationService = useService("notification");
+  notificationService.add("I'm a very simple notification"); 
+  
+API
+~~~
+
+.. js:function:: add(message[, options])
+  
+    :param string message: the notification message to display
+    :param object options: the options of the notification
+    :returns: a function to close the notification
+
+    Shows a notification.
+
+    The options are defined by:
+
+    .. list-table::
+      :widths: 15 30 55
+      :header-rows: 1
+
+      * - Name
+        - Type
+        - Description
+      * - `title`
+        - string
+        - Add a title to the notification
+      * - `type`
+        - `warning` | `danger` | `success` | `info`
+        - Changes the background color according to the type
+      * - `sticky`
+        - boolean
+        - Whether or not the notification should stay until dismissed
+      * - `className`
+        - string
+        - additional css class that will be added to the notification
+      * - `onClose`
+        - function
+        - callback to be executed when the notification closes
+      * - `buttons`
+        - button[] (see below)
+        - list of button to display in the notification
+
+    The buttons are defined by:
+
+    .. list-table::
+      :widths: 15 30 55
+      :header-rows: 1
+
+      * - Name
+        - Type
+        - Description
+      * - `name`
+        - string
+        - The button text
+      * - `onClick`
+        - function
+        - callback to execute when the button is clicked
+      * - `primary`
+        - boolean
+        - whether the button should be styled as a primary button
+
+Examples
+~~~~~~~~
+
+A notification for when a sale deal is made with a button to go some kind of commission page.
+
+.. code-block:: javascript
+    
+  // in setup
+  this.notificationService = useService("notification");
+  this.actionService = useService("actionService");
+
+  // later
+  this.notificationService.add("You closed a deal!", {
+    title: "Congrats",
+    type: "success",
+    buttons: [
+        {
+            name: "See your Commission",
+            onClick: () => {
+                this.actionService.doAction("commission_action");
+            },
+        },
+    ],
+  });
+
+.. image:: images/notification_service.png
+  :width: 600 px
+  :alt: Example of notification
+  :align: center
+
+A notification that closes after a second:
+
+.. code-block:: javascript
+
+  const notificationService = useService("notification");
+  const close = notificationService.add("I will be quickly closed");
+  setTimeout(close, 1000);
+
 .. _services/rpc:
 
 RPC service
@@ -256,8 +372,9 @@ When a rpc fails, then:
 
   If it is a network error, then the error description is simply an object
   ``{type: 'network'}``.
-  When a network error occurs, a notification is displayed and the server is regularly
+  When a network error occurs, a :ref:`notification <services/notification>` is
-  contacted until it responds. The notification is closed as soon as the server responds.
+  displayed and the server is regularly contacted until it responds. The
+  notification is closed as soon as the server responds.
 
 .. _services/title:
 
@@ -425,96 +542,3 @@ API
     .. code-block:: js
 
       const isInSalesGroup = await userService.hasGroup("sale.group_sales")
-
-Notification service
---------------------
-
-Overview
-~~~~~~~~
-
-* Technical name: `notification`
-* Dependencies: None
-
-The `notification` service allows to display notifications on the screen.
-  
-.. code-block:: javascript
-
-  const notificationService = useService("notification");
-  notificationService.add("I'm a very simple notification"); 
-  
-API
-~~~
-
-.. js:function:: add(message[, options])
-  
-    :param string message: the notification message to display
-    :param object options: the options of the notification
-    :returns: a function to close the notification
-
-    Shows a notification.
-
-The options are defined by:
-
-.. code-block:: ts 
-
-   @typedef {Object} NotificationOptions
-   @property {string} [title]
-   // Add a title to the notification
-   @property {"warning" | "danger" | "success" | "info"} [type]
-   // Change the background color
-   @property {boolean} [sticky=false]
-   // Whether or not the notification shouldn't be dismissed
-   @property {string} [className]
-   // Add a class name of the notification for css targetting
-   @property {function(): void} [onClose]
-   // Provide a callback to be executed when the notification closes
-   @property {NotificationButton[]} [buttons]
-   // Add buttons to the notifications. 
-
-   @typedef {Object} NotificationButton
-   @property {string} name
-   // The button text
-   @property {function(): void} onClick
-   // The callback to execute when the button is clicked
-   @property {string} [icon]
-   // A font-awesome string to add an icon
-   @property {boolean} [primary=false]
-   // Wheter the button has the primary button style
-
-Examples
-~~~~~~~~
-
-A notification for when a sale deal is made with a button to go some kind of commission page.
-
-.. code-block:: javascript
-    
-  // in setup
-  this.notificationService = useService("notification");
-  this.actionService = useService("actionService");
-
-  // later
-  this.notificationService.add("You closed a deal!", {
-    title: "Congrats",
-    type: "success",
-    buttons: [
-        {
-            name: "See your Commission",
-            onClick: () => {
-                this.actionService.doAction("commission_action");
-            },
-        },
-    ],
-  });
-
-.. image:: images/notification_service.png
-  :width: 600 px
-  :alt: Example of notification
-  :align: center
-
-A notification that closes after a second:
-
-.. code-block:: javascript
-
-  const notificationService = useService("notification");
-  const close = notificationService.add("I will be quickly closed");
-  setTimeout(close, 1000);