[DOC] web: amelioration of inline documentation

1 files changed, 27 insertions, 16 deletions

diff --git a/addons/web/static/src/js/widgets/dropdown_menu.js b/addons/web/static/src/js/widgets/dropdown_menu.js
index d7e4bff32a4..2999d09bbf9 100644
--- a/addons/web/static/src/js/widgets/dropdown_menu.js
+++ b/addons/web/static/src/js/widgets/dropdown_menu.js
@@ -6,17 +6,7 @@ var Widget = require('web.Widget');
 
 var QWeb = core.qweb;
 
-// interface IItem {
-//     itemId: string;
-//     description: string;
-//     groupId: string;
-//     isActive: boolean; (optional)
-//     isOpen: boolean; (optional)
-//     isRemovable: boolean; (optional)
-//     options: array of objects with 'optionId' and 'description' keys; (optional)
-//     defaultOptionId: string refers to an optionId (optional)
-//     currentOptionId: string refers to an optionId that is activated if item is active (optional)
-// }
+
 
 var DropdownMenu = Widget.extend({
     template: 'web.DropdownMenu',
@@ -29,10 +19,28 @@ var DropdownMenu = Widget.extend({
     },
 
     /**
+     * override
+     *
      * @param {Widget} parent
-     * @param {Object} dropdowHeader object with keys 'title' and 'icon'
-     * @param {Object} items values are arrays of items (see interface IItems)
-     * @param {Object} itemGenerator
+     * @param {Object} dropdowHeader object used to customize the dropdown menu. The keys:
+     *                      - 'title' (e.g. 'Group By')
+     *                      - 'icon' (e.g. 'fa-bars')
+     *                      - 'symbol' (e.g. 'caret')
+     *                      - 'category' (describes the type of items)
+     *                      - 'style' (button style)
+     * @param {Object} items list of menu items (type IGMenuItem below)
+     *   interface IMenuItem {
+     *      itemId: string; unique id associated with the item
+     *      description: string; label printed on screen
+     *      groupId: string;
+     *      isActive: boolean; (optional) determines if the item is considered active
+     *      isOpen: boolean; (optional) in case there are options the submenu presenting the options
+     *                                is opened or closed according to isOpen
+     *      isRemovable: boolean; (optional) can be removed from menu
+     *      options: array of objects with 'optionId' and 'description' keys; (optional)
+     *      defaultOptionId: string refers to an optionId (optional)
+     *      currentOptionId: string refers to an optionId that is activated if item is active (optional)
+     *   }
      */
     init: function (parent, dropdownHeader, items) {
         this._super(parent);
@@ -93,7 +101,6 @@ var DropdownMenu = Widget.extend({
         };
         this.trigger_up('menu_item_deleted', eventData);
     },
-
     /**
      * @private
      */
@@ -103,6 +110,9 @@ var DropdownMenu = Widget.extend({
         this.$('ul.o_dropdown_menu').prepend($(newMenuItems));
     },
     /**
+     * this function computes some default values for some of the item keys
+     * according to values passed at initialization
+     *
      * @private
      * @param {Object} item
      */
@@ -181,6 +191,7 @@ var DropdownMenu = Widget.extend({
     //--------------------------------------------------------------------------
     // Handlers
     //--------------------------------------------------------------------------
+
     /**
      * This method is called when Bootstrap trigger a 'close' event (for example
      * when the user clicks outside the dropdown menu).
@@ -240,4 +251,4 @@ var DropdownMenu = Widget.extend({
 
 return DropdownMenu;
 
-});
\ No newline at end of file
+});