[DOC] web: amelioration of inline documentation

3 files changed, 93 insertions, 50 deletions

diff --git a/addons/web/static/src/js/views/search/search_inputs.js b/addons/web/static/src/js/views/search/search_inputs.js
index 3366fe91ecb..00d4d6281a0 100644
--- a/addons/web/static/src/js/views/search/search_inputs.js
+++ b/addons/web/static/src/js/views/search/search_inputs.js
@@ -514,6 +514,9 @@ var FilterGroup = Input.extend(/** @lends instance.web.search.FilterGroup# */{
      *
      * @param {Array<instance.web.search.Filter>} filters elements of the group
      * @param {instance.web.SearchView} parent parent in which the filters are contained
+     * @param {Object} intervalMapping, a key is a field name and the corresponding value
+     *                   is the current interval used
+     *                   (necessarily the field is of type 'date' or 'datetime')
      */
     init: function (filters, parent, intervalMapping) {
         // If all filters are group_by and we're not initializing a GroupbyGroup,
@@ -701,6 +704,11 @@ var FilterGroup = Input.extend(/** @lends instance.web.search.FilterGroup# */{
             };
         }));
     },
+    /*
+     * private
+     *
+     * @param {Object} intervalMapping
+     */
     updateIntervalMapping: function (intervalMapping) {
         this.intervalMapping = intervalMapping;
     }
diff --git a/addons/web/static/src/js/views/search/search_view.js b/addons/web/static/src/js/views/search/search_view.js
index e307ca2a240..098df30c46a 100644
--- a/addons/web/static/src/js/views/search/search_view.js
+++ b/addons/web/static/src/js/views/search/search_view.js
@@ -187,6 +187,13 @@ var FacetView = Widget.extend({
             }
         }
     },
+    /*
+     * @param {Widget} parent
+     * @param {Object} model
+     * @param {Object} intervalMapping, a key is a field name and the corresponding value
+     *                   is the current interval used
+     *                   (necessarily the field is of type 'date' or 'datetime')
+     */
     init: function (parent, model, intervalMapping) {
         this._super(parent);
         this.model = model;
@@ -218,6 +225,13 @@ var FacetView = Widget.extend({
 
 var FacetValueView = Widget.extend({
     template: 'SearchView.FacetView.Value',
+    /*
+     * @param {Widget} parent
+     * @param {Object} model
+     * @param {Object} interval (optional) is used in case the facet value
+     *                  corresponds to a groupby with an associated 'date'
+     *                  'datetime' field.
+     */
     init: function (parent, model, interval) {
         this._super(parent);
         this.model = model;
@@ -275,10 +289,10 @@ var SearchView = Widget.extend({
         },
     },
     custom_events: {
-        'menu_item_toggled': '_onItemToggled',
-        'item_option_changed': '_onItemOptionChanged',
-        'new_groupby': '_onNewGroupby',
-        'new_filter': '_onNewFilter',
+        menu_item_toggled: '_onItemToggled',
+        item_option_changed: '_onItemOptionChanged',
+        new_groupby: '_onNewGroupby',
+        new_filter: '_onNewFilter',
     },
     defaults: _.extend({}, Widget.prototype.defaults, {
         hidden: false,
@@ -832,7 +846,7 @@ var SearchView = Widget.extend({
                         groupId: groupId,
                         defaultOptionId: defaultOptionId,
                     });
-                    if (self._fieldIsDate(fieldName)) {
+                    if (_.contains(['date', 'datetime'], self.fields[fieldName].type)) {
                         self.intervalMapping.push({groupby: groupby, interval: defaultOptionId || 'month'});
 
                     }
@@ -844,15 +858,6 @@ var SearchView = Widget.extend({
         });
         return new GroupByMenu(this, groupbys, this.fields);
     },
-
-
-    _fieldIsDate: function (fieldName) {
-        if (_.contains(['date', 'datetime'], this.fields[fieldName].type)) {
-            return true;
-        }
-        return false;
-    },
-
     /**
      * Processes a fieldsView in place. In particular, parses its arch.
      *
@@ -869,8 +874,12 @@ var SearchView = Widget.extend({
         return fv;
     },
     /**
+     * This function ask the groupby menu to deactive all groupbys with
+     * corresponding groupId in the list selectedGroupIds.
+     * (TO DO: simplify method... actually there is only one group of groupbys)
+     *
      * @private
-     * @param {string[]]} selectedGroupIds
+     * @param {string[]]} selectedGroupIds list of group ids to deactivate
      */
     _unsetUnusedGroupbys: function (selectedGroupIds) {
         var groupIds = this.selectedGroupIds.groupByCategory.reduce(
@@ -886,6 +895,9 @@ var SearchView = Widget.extend({
         this.groupby_menu.unsetGroups(groupIds);
     },
     /**
+     * This function ask the filters menu to deactive all filters with
+     * corresponding groupId in the list selectedGroupIds.
+     *
      * @private
      * @param {string[]]} selectedGroupIds
      */
@@ -909,6 +921,11 @@ var SearchView = Widget.extend({
 
     /**
      *
+     * this function is called in response to an event 'on_item_toggled'.
+     * this kind of event is triggered by the filters menu or the groupby menu
+     * when a user has clicked on a item (a filter or a groupby).
+     * The query is modified accordingly to the new state (active or not) of that item
+     *
      * @private
      * @param {OdooEvent} event
      */
@@ -931,16 +948,19 @@ var SearchView = Widget.extend({
         }
     },
     /**
+     * this function is called when a new groupby has been added to the groupby menu
+     * via the 'Add Custom Groupby' submenu. The query is modified with the new groupby
+     * added to it as active. The communication betwenn the groupby menu and the search view
+     * is maintained by properly updating the mappings.
      * @private
      * @param {OdooEvent} event
      */
     _onNewGroupby: function (event) {
         var attrs = {
-                context:"{'group_by':'" + event.data.fieldName + "''}",
-                name: event.data.description,
-                fieldName: event.data.fieldName,
-            };
-
+            context:"{'group_by':'" + event.data.fieldName + "''}",
+            name: event.data.description,
+            fieldName: event.data.fieldName,
+        };
         var groupby = new search_inputs.Filter({attrs: attrs}, this);
         if (event.data.optionId) {
             var interval = event.data.optionId;
@@ -959,7 +979,11 @@ var SearchView = Widget.extend({
             category: 'Group By',
         });
     },
-        /**
+    /**
+     * this function is called when a new filter has been added to the filters menu
+     * via the 'Add Custom Filter' submenu. The query is modified with the new filter
+     * added to it as active. The communication betwenn the filters menu and the search view
+     * is maintained by properly updating the mappings.
      * @private
      * @param {OdooEvent} event
      */
@@ -970,25 +994,23 @@ var SearchView = Widget.extend({
         var groupId;
 
         _.each(event.data, function (filterDescription) {
-                filter = new search_inputs.Filter(filterDescription.filter, this);
-                filters.push(filter);
-                self.filtersMapping.push({
-                    filterId: filterDescription.itemId,
-                    filter: filter,
-                    groupId: filterDescription.groupId,
-                });
-                // filters belong to the same group
-                if (!groupId) {
-                    groupId = filterDescription.groupId;
-                }
+            filter = new search_inputs.Filter(filterDescription.filter, this);
+            filters.push(filter);
+            self.filtersMapping.push({
+                filterId: filterDescription.itemId,
+                filter: filter,
+                groupId: filterDescription.groupId,
             });
+            // filters belong to the same group
+            if (!groupId) {
+                groupId = filterDescription.groupId;
+            }
+        });
         var group = new search_inputs.FilterGroup(filters, this, this.intervalMapping);
         filters.forEach(function (filter) {
             group.toggle(filter, {silent: true});
         });
         this.query.trigger('reset');
-
-
         this.groupsMapping.push({
             groupId: groupId,
             group: group,
@@ -996,6 +1018,8 @@ var SearchView = Widget.extend({
         });
     },
     /**
+     * this function is called when the option related to an item (filter or groupby) has been
+     * changed by the user. The query is modified appropriately.
      *
      * @private
      * @param {OdooEvent} event
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
+});