From f1a85ba70a2412fb0d7bf789a758d8f2d2e86a02 Mon Sep 17 00:00:00 2001 From: Xavier Morel Date: Mon, 18 Sep 2017 10:03:51 +0200 Subject: [FIX] *: fix a bunch of incorrectly documented docstring Fix a bunch of ill-documented/incomplete/incorrect method docs Without this, the automatic doc generation does not work. --- addons/web/static/src/js/core/ajax.js | 2 +- addons/web/static/src/js/core/bus.js | 2 + addons/web/static/src/js/core/class.js | 57 +++++++++++------------ addons/web/static/src/js/core/concurrency.js | 15 +++--- addons/web/static/src/js/core/dialog.js | 14 +++--- addons/web/static/src/js/core/dom.js | 8 +++- addons/web/static/src/js/core/mixins.js | 64 ++++++++++++++++---------- addons/web/static/src/js/core/pyeval.js | 10 ++-- addons/web/static/src/js/core/session.js | 4 +- addons/web/static/src/js/core/translation.js | 10 ++++ addons/web/static/src/js/core/utils.js | 12 ++--- addons/web/static/src/js/core/widget.js | 68 ++++++++++++++-------------- 12 files changed, 148 insertions(+), 118 deletions(-) (limited to 'addons/web/static/src/js/core') diff --git a/addons/web/static/src/js/core/ajax.js b/addons/web/static/src/js/core/ajax.js index 5bab96a0c1e..d69574d2e10 100644 --- a/addons/web/static/src/js/core/ajax.js +++ b/addons/web/static/src/js/core/ajax.js @@ -211,7 +211,7 @@ var loadJS = (function () { * @param {HTMLFormElement} [options.form] the form to submit in order to fetch the file * @param {Function} [options.success] callback in case of download success * @param {Function} [options.error] callback in case of request error, provided with the error body - * @param {Function} [options.complete] called after both ``success`` and ``error` callbacks have executed + * @param {Function} [options.complete] called after both ``success`` and ``error`` callbacks have executed */ function get_file(options) { // need to detect when the file is done downloading (not used diff --git a/addons/web/static/src/js/core/bus.js b/addons/web/static/src/js/core/bus.js index bf33c1fe01e..1f715da4df1 100644 --- a/addons/web/static/src/js/core/bus.js +++ b/addons/web/static/src/js/core/bus.js @@ -6,6 +6,8 @@ var mixins = require('web.mixins'); /** * Event Bus used to bind events scoped in the current instance + * + * @class Bus */ return Class.extend(mixins.EventDispatcherMixin, { init: function() { diff --git a/addons/web/static/src/js/core/class.js b/addons/web/static/src/js/core/class.js index 8e53f0ba06d..4d1e6baaa8e 100644 --- a/addons/web/static/src/js/core/class.js +++ b/addons/web/static/src/js/core/class.js @@ -12,46 +12,47 @@ odoo.define('web.Class', function () { * Defines The Class object. That object can be used to define and inherit classes using * the extend() method. * - * Example: + * Example:: * - * var Person = Class.extend({ - * init: function(isDancing){ - * this.dancing = isDancing; - * }, - * dance: function(){ - * return this.dancing; - * } - * }); + * var Person = Class.extend({ + * init: function(isDancing){ + * this.dancing = isDancing; + * }, + * dance: function(){ + * return this.dancing; + * } + * }); * - * The init() method act as a constructor. This class can be instancied this way: + * The init() method act as a constructor. This class can be instanced this way:: * - * var person = new Person(true); - * person.dance(); + * var person = new Person(true); + * person.dance(); * - * The Person class can also be extended again: + * The Person class can also be extended again: * - * var Ninja = Person.extend({ - * init: function(){ - * this._super( false ); - * }, - * dance: function(){ - * // Call the inherited version of dance() - * return this._super(); - * }, - * swingSword: function(){ - * return true; - * } - * }); + * var Ninja = Person.extend({ + * init: function(){ + * this._super( false ); + * }, + * dance: function(){ + * // Call the inherited version of dance() + * return this._super(); + * }, + * swingSword: function(){ + * return true; + * } + * }); * * When extending a class, each re-defined method can use this._super() to call the previous * implementation of that method. + * + * @class Class */ +function OdooClass(){} + var initializing = false; var fnTest = /xyz/.test(function(){xyz();}) ? /\b_super\b/ : /.*/; -// The web Class implementation (does nothing) -function OdooClass(){}; - /** * Subclass an existing class * diff --git a/addons/web/static/src/js/core/concurrency.js b/addons/web/static/src/js/core/concurrency.js index cab9df6529e..aeef29809d9 100644 --- a/addons/web/static/src/js/core/concurrency.js +++ b/addons/web/static/src/js/core/concurrency.js @@ -122,7 +122,7 @@ return { * the last operation. * * For example, let us say that we have a _fetch method on a widget which - * fetches data. We want to rerender the widget after. We could do this: + * fetches data. We want to rerender the widget after. We could do this:: * * this._fetch().then(function (result) { * self.state = result; @@ -130,17 +130,18 @@ return { * }); * * Now, we have at least two problems: + * * - if this code is called twice and the second _fetch completes before the * first, the end state will be the result of the first _fetch, which is * not what we expect * - in any cases, the user interface will rerender twice, which is bad. * - * Now, if we have a DropPrevious: + * Now, if we have a DropPrevious:: * * this.dropPrevious = new DropPrevious(); * * Then we can wrap the _fetch in a DropPrevious and have the expected - * result: + * result:: * * this.dropPrevious * .add(this._fetch()) @@ -153,7 +154,7 @@ return { /** * Registers a new deferred and rejects the previous one * - * @param {Deferred} the new deferred + * @param {Deferred} deferred the new deferred * @returns {Promise} */ add: function (deferred) { @@ -171,7 +172,7 @@ return { * * Imagine that we have a function to fetch some data _load(), which returns * a deferred which resolves to something useful. Now, we have some code - * looking like this: + * looking like this:: * * return this._load().then(function (result) { * this.state = result; @@ -179,11 +180,11 @@ return { * * If this code is run twice, but the second execution ends before the * first, then the final state will be the result of the first call to - * _load. However, if we have a mutex: + * _load. However, if we have a mutex:: * * this.mutex = new Mutex(); * - * and if we wrap the calls to _load in a mutex: + * and if we wrap the calls to _load in a mutex:: * * return this.mutex.exec(function() { * return this._load().then(function (result) { diff --git a/addons/web/static/src/js/core/dialog.js b/addons/web/static/src/js/core/dialog.js index 88bfae2b545..8c75db392fb 100644 --- a/addons/web/static/src/js/core/dialog.js +++ b/addons/web/static/src/js/core/dialog.js @@ -9,17 +9,17 @@ var QWeb = core.qweb; var _t = core._t; /** - A useful class to handle dialogs. - - Attributes: - - $footer: A jQuery element targeting a dom part where buttons can be added. It always exists - during the lifecycle of the dialog. -*/ + * A useful class to handle dialogs. + * Attributes: + * + * ``$footer`` + * A jQuery element targeting a dom part where buttons can be added. It + * always exists during the lifecycle of the dialog. + **/ var Dialog = Widget.extend({ xmlDependencies: ['/web/static/src/xml/dialog.xml'], /** - * @constructor * @param {Widget} parent * @param {Object} [options] * @param {string} [options.title=Odoo] diff --git a/addons/web/static/src/js/core/dom.js b/addons/web/static/src/js/core/dom.js index 7bae1bc29a5..6ca13f18e4e 100644 --- a/addons/web/static/src/js/core/dom.js +++ b/addons/web/static/src/js/core/dom.js @@ -115,10 +115,14 @@ return { } }, /** - * jQuery find function behavior is: + * jQuery find function behavior is:: + * * $('A').find('A B') <=> $('A A B') - * The searches behavior to find options' DOM needs to be + * + * The searches behavior to find options' DOM needs to be:: + * * $('A').find('A B') <=> $('A B') + * * This is what this function does. * * @param {jQuery} $from - the jQuery element(s) from which to search diff --git a/addons/web/static/src/js/core/mixins.js b/addons/web/static/src/js/core/mixins.js index cc99cc1aaa4..79de054bf10 100644 --- a/addons/web/static/src/js/core/mixins.js +++ b/addons/web/static/src/js/core/mixins.js @@ -10,6 +10,9 @@ var AbstractService = require('web.AbstractService'); * relationship. Each object can a have a parent and multiple children. * When an object is destroyed, all its children are destroyed too releasing * any resource they could have reserved before. + * + * @name ParentedMixin + * @mixin */ var ParentedMixin = { __parentedMixin : true, @@ -57,21 +60,21 @@ var ParentedMixin = { return this.__parentedDestroyed; }, /** - Utility method to only execute asynchronous actions if the current - object has not been destroyed. - - @param {$.Deferred} promise The promise representing the asynchronous - action. - @param {bool} [reject=false] If true, the returned promise will be - rejected with no arguments if the current - object is destroyed. If false, the - returned promise will never be resolved - or rejected. - @returns {$.Deferred} A promise that will mirror the given promise if - everything goes fine but will either be rejected - with no arguments or never resolved if the - current object is destroyed. - */ + * Utility method to only execute asynchronous actions if the current + * object has not been destroyed. + * + * @param {$.Deferred} promise The promise representing the asynchronous + * action. + * @param {bool} [reject=false] If true, the returned promise will be + * rejected with no arguments if the current + * object is destroyed. If false, the + * returned promise will never be resolved + * or rejected. + * @returns {$.Deferred} A promise that will mirror the given promise if + * everything goes fine but will either be rejected + * with no arguments or never resolved if the + * current object is destroyed. + */ alive: function (promise, reject) { var self = this; return $.Deferred(function (def) { @@ -228,13 +231,16 @@ var Events = Class.extend({ }); /** - Mixin containing an event system. Events are also registered by specifying the target object - (the object which will receive the event when it is raised). Both the event-emitting object - and the target object store or reference to each other. This is used to correctly remove all - reference to the event handler when any of the object is destroyed (when the destroy() method - from ParentedMixin is called). Removing those references is necessary to avoid memory leak - and phantom events (events which are raised and sent to a previously destroyed object). -*/ + * Mixin containing an event system. Events are also registered by specifying the target object + * (the object which will receive the event when it is raised). Both the event-emitting object + * and the target object store or reference to each other. This is used to correctly remove all + * reference to the event handler when any of the object is destroyed (when the destroy() method + * from ParentedMixin is called). Removing those references is necessary to avoid memory leak + * and phantom events (events which are raised and sent to a previously destroyed object). + * + * @name EventDispatcherMixin + * @mixin + */ var EventDispatcherMixin = _.extend({}, ParentedMixin, { __eventDispatcherMixin: true, custom_events: {}, @@ -349,6 +355,10 @@ var EventDispatcherMixin = _.extend({}, ParentedMixin, { } }); +/** + * @name PropertiesMixin + * @mixin + */ var PropertiesMixin = _.extend({}, EventDispatcherMixin, { init: function () { EventDispatcherMixin.init.call(this); @@ -432,6 +442,10 @@ odoo.define('web.ServicesMixin', function (require) { var rpc = require('web.rpc'); +/** + * @mixin + * @name ServicesMixin + */ var ServicesMixin = { call: function (service, method) { var args = Array.prototype.slice.call(arguments, 2); @@ -450,9 +464,9 @@ var ServicesMixin = { * Builds and executes RPC query. Returns a deferred's promise resolved with * the RPC result. * - * @param {string} arg1 either a route or a model - * @param {string} method if a model is given, this argument is a method - * @returns {Deferred's Promise} + * @param {string} params either a route or a model + * @param {string} options if a model is given, this argument is a method + * @returns {Promise} */ _rpc: function (params, options) { var query = rpc.buildQuery(params); diff --git a/addons/web/static/src/js/core/pyeval.js b/addons/web/static/src/js/core/pyeval.js index 502c6a4ce90..ee4ac697fd9 100644 --- a/addons/web/static/src/js/core/pyeval.js +++ b/addons/web/static/src/js/core/pyeval.js @@ -530,11 +530,11 @@ datetime.date = py.type('date', null, { }), }); /** - Returns the current local date, which means the date on the client (which can be different - compared to the date of the server). - - @return {datetime.date} -*/ + * Returns the current local date, which means the date on the client (which can be different + * compared to the date of the server). + * + * @return {datetime.date} + */ function context_today() { var d = new Date(); return py.PY_call( diff --git a/addons/web/static/src/js/core/session.js b/addons/web/static/src/js/core/session.js index fc45e669407..0ecea92fb71 100644 --- a/addons/web/static/src/js/core/session.js +++ b/addons/web/static/src/js/core/session.js @@ -321,8 +321,6 @@ var Session = core.Class.extend(mixins.EventDispatcherMixin, { * @param {String} url RPC endpoint * @param {Object} params call parameters * @param {Object} options additional options for rpc call - * @param {Function} success_callback function to execute on RPC call success - * @param {Function} error_callback function to execute on RPC call failure * @returns {jQuery.Deferred} jquery-provided ajax deferred */ rpc: function (url, params, options) { @@ -413,7 +411,7 @@ var Session = core.Class.extend(mixins.EventDispatcherMixin, { * (host system settings) to UTC, for a given date. The offset is positive * if the local timezone is behind UTC, and negative if it is ahead. * - * @param {string || moment} date a valid string date or moment instance + * @param {string | moment} date a valid string date or moment instance * @returns {integer} */ getTZOffset: function (date) { diff --git a/addons/web/static/src/js/core/translation.js b/addons/web/static/src/js/core/translation.js index fae44774a07..76493fdb432 100644 --- a/addons/web/static/src/js/core/translation.js +++ b/addons/web/static/src/js/core/translation.js @@ -71,6 +71,16 @@ var TranslationDataBase = Class.extend(/** @lends instance.TranslationDataBase# } }); +/** + * Eager translation function, performs translation immediately at call + * site. Beware using this outside of method bodies (before the + * translation database is loaded), you probably want :func:`_lt` + * instead. + * + * @function _t + * @param {String} source string to translate + * @returns {String} source translated into the current locale + */ var _t = new TranslationDataBase().build_translation_function(); /** * Lazy translation function, only performs the translation when actually diff --git a/addons/web/static/src/js/core/utils.js b/addons/web/static/src/js/core/utils.js index 585be4d37b8..9eefc12944c 100644 --- a/addons/web/static/src/js/core/utils.js +++ b/addons/web/static/src/js/core/utils.js @@ -107,7 +107,7 @@ var utils = { /** * Returns a human readable size * - * @param {Number} number of bytes + * @param {Number} size number of bytes */ human_size: function (size) { var units = _t("Bytes,Kb,Mb,Gb,Tb,Pb,Eb,Zb,Yb").split(','); @@ -271,8 +271,8 @@ var utils = { /** * performs a half up rounding with a fixed amount of decimals, correcting for float loss of precision * See the corresponding float_round() in server/tools/float_utils.py for more info - * @param {Number} the value to be rounded - * @param {Number} the number of decimals. eg: round_decimals(3.141592,2) -> 3.14 + * @param {Number} value the value to be rounded + * @param {Number} decimals the number of decimals. eg: round_decimals(3.141592,2) -> 3.14 */ round_decimals: function (value, decimals) { return utils.round_precision(value, Math.pow(10,-decimals)); @@ -319,9 +319,9 @@ var utils = { }, /** * Create a cookie - * @param {String} name : the name of the cookie - * @param {String} value : the value stored in the cookie - * @param {Integer} ttl : time to live of the cookie in millis. -1 to erase the cookie. + * @param {String} name the name of the cookie + * @param {String} value the value stored in the cookie + * @param {Integer} ttl time to live of the cookie in millis. -1 to erase the cookie. */ set_cookie: function (name, value, ttl) { ttl = ttl || 24*60*60*365; diff --git a/addons/web/static/src/js/core/widget.js b/addons/web/static/src/js/core/widget.js index 8ef141a6020..c47deff7330 100644 --- a/addons/web/static/src/js/core/widget.js +++ b/addons/web/static/src/js/core/widget.js @@ -7,50 +7,51 @@ var mixins = require('web.mixins'); var ServicesMixin = require('web.ServicesMixin'); /** - * Base class for all visual components. Provides a lot of functionalities helpful + * Base class for all visual components. Provides a lot of functions helpful * for the management of a part of the DOM. * * Widget handles: + * * - Rendering with QWeb. - * - Life-cycle management and parenting (when a parent is destroyed, all its children are - * destroyed too). + * - Life-cycle management and parenting (when a parent is destroyed, all its + * children are destroyed too). * - Insertion in DOM. * - * Guide to create implementations of the Widget class: - * ============================================== + * **Guide to create implementations of the Widget class** * - * Here is a sample child class: + * Here is a sample child class:: * - * MyWidget = openerp.base.Widget.extend({ - * // the name of the QWeb template to use for rendering - * template: "MyQWebTemplate", + * var MyWidget = openerp.base.Widget.extend({ + * // the name of the QWeb template to use for rendering + * template: "MyQWebTemplate", * - * init: function(parent) { - * this._super(parent); - * // stuff that you want to init before the rendering - * }, - * start: function() { - * // stuff you want to make after the rendering, `this.$el` holds a correct value - * this.$(".my_button").click(/* an example of event binding * /); + * init: function(parent) { + * this._super(parent); + * // stuff that you want to init before the rendering + * }, + * start: function() { + * // stuff you want to make after the rendering, `this.$el` holds a correct value + * this.$(".my_button").click(/* an example of event binding * /); * - * // if you have some asynchronous operations, it's a good idea to return - * // a promise in start() - * var promise = this._rpc(...); - * return promise; - * } - * }); + * // if you have some asynchronous operations, it's a good idea to return + * // a promise in start() + * var promise = this._rpc(...); + * return promise; + * } + * }); * - * Now this class can simply be used with the following syntax: + * Now this class can simply be used with the following syntax:: * - * var my_widget = new MyWidget(this); - * my_widget.appendTo($(".some-div")); + * var my_widget = new MyWidget(this); + * my_widget.appendTo($(".some-div")); * - * With these two lines, the MyWidget instance was inited, rendered, it was inserted into the - * DOM inside the ".some-div" div and its events were binded. + * With these two lines, the MyWidget instance was initialized, rendered, + * inserted into the DOM inside the ``.some-div`` div and its events were + * bound. * - * And of course, when you don't need that widget anymore, just do: + * And of course, when you don't need that widget anymore, just do:: * - * my_widget.destroy(); + * my_widget.destroy(); * * That will kill the widget in a clean way and erase its content from the dom. */ @@ -67,7 +68,7 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, { * The name of the QWeb template that will be used for rendering. Must be * redefined in subclasses or the default render() method can not be used. * - * @type string + * @type {String} */ template: null, /** @@ -82,8 +83,6 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, { /** * Constructs the widget and sets its parent if a parent is given. * - * @constructs openerp.Widget - * * @param {openerp.Widget} parent Binds the current instance to the given Widget instance. * When that widget is destroyed by calling destroy(), the current instance will be * destroyed too. Can be null. @@ -238,7 +237,7 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, { * (if any) by the new one in the DOM. * * @param {HTMLElement | jQuery} $el - * @returns {*} this + * @returns {Widget} this */ replaceElement: function ($el) { var $oldel = this.$el; @@ -257,13 +256,14 @@ var Widget = core.Class.extend(mixins.PropertiesMixin, ServicesMixin, { * Re-sets the widget's root element (el/$el/$el). * * Includes: + * * * re-delegating events * * re-binding sub-elements * * if the widget already had a root element, replacing the pre-existing * element in the DOM * * @param {HTMLElement | jQuery} element new root element for the widget - * @return {*} this + * @return {Widget} this */ setElement: function (element) { // NB: completely useless, as WidgetMixin#init creates a $el -- cgit v1.2.3