From 192af7a8e089c3158ec1be6a3e61aa462a2fe9c3 Mon Sep 17 00:00:00 2001 From: polesye Date: Tue, 8 Apr 2014 10:00:53 +0300 Subject: [PATCH] Update docstrings. --- .../xmodule/js/src/video/00_iterator.js | 47 ++++------ .../js/src/video/08_video_speed_control.js | 91 +++++++------------ 2 files changed, 53 insertions(+), 85 deletions(-) diff --git a/common/lib/xmodule/xmodule/js/src/video/00_iterator.js b/common/lib/xmodule/xmodule/js/src/video/00_iterator.js index f6daf04b07..c6980b29ac 100644 --- a/common/lib/xmodule/xmodule/js/src/video/00_iterator.js +++ b/common/lib/xmodule/xmodule/js/src/video/00_iterator.js @@ -5,10 +5,10 @@ define( function() { "use strict"; /** - * @desc Provides convenient way to work with iterate able data. - * + * Provides convenient way to work with iterable data. + * @exports video/00_iterator.js + * @constructor * @param {array} list Array to be iterated. - * */ var Iterator = function (list) { this.list = list; @@ -20,22 +20,19 @@ function() { Iterator.prototype = { /** - * @desc Returns `true` if current index is valid for the iterator. - * + * Checks validity of provided index for the iterator. * @access protected - * @returns {boolean} - * + * @param {numebr} index + * @return {boolean} */ _isValid: function (index) { return _.isNumber(index) && index < this.size && index >= 0; }, /** - * @desc Returns next element. - * - * @param {number} index If set, updates current index of iterator. - * @returns {any} - * + * Returns next element. + * @param {number} [index] Updates current position. + * @return {any} */ next: function (index) { if (!(this._isValid(index))) { @@ -48,11 +45,9 @@ function() { }, /** - * @desc Returns previous element. - * - * @param {number} index If set, updates current index of iterator. - * @returns {any} - * + * Returns previous element. + * @param {number} [index] Updates current position. + * @return {any} */ prev: function (index) { if (!(this._isValid(index))) { @@ -65,30 +60,24 @@ function() { }, /** - * @desc Returns last element in the list. - * - * @returns {any} - * + * Returns last element in the list. + * @return {any} */ last: function () { return this.list[this.lastIndex]; }, /** - * @desc Returns first element in the list. - * - * @returns {any} - * + * Returns first element in the list. + * @return {any} */ first: function () { return this.list[0]; }, /** - * @desc Returns `true` if current position is last for the iterator. - * - * @returns {boolean} - * + * Returns `true` if current position is last for the iterator. + * @return {boolean} */ isEnd: function () { return this.index === this.lastIndex; diff --git a/common/lib/xmodule/xmodule/js/src/video/08_video_speed_control.js b/common/lib/xmodule/xmodule/js/src/video/08_video_speed_control.js index edb0e321e1..50c2a0d703 100644 --- a/common/lib/xmodule/xmodule/js/src/video/08_video_speed_control.js +++ b/common/lib/xmodule/xmodule/js/src/video/08_video_speed_control.js @@ -4,6 +4,12 @@ define( ['video/00_iterator.js'], function (Iterator) { "use strict"; + /** + * Video speed control module. + * @exports video/08_video_speed_control.js + * @constructor + * @param {object} state The object containing the state of the video player. + */ var SpeedControl = function (state) { if (!(this instanceof SpeedControl)) { return new SpeedControl(state); @@ -17,10 +23,7 @@ function (Iterator) { }; SpeedControl.prototype = { - /** - * @desc Initializes the module. - * - */ + /** Initializes the module. */ initialize: function () { var state = this.state; @@ -44,12 +47,10 @@ function (Iterator) { }, /** - * @desc Create any necessary DOM elements, attach them, and set their, + * Creates any necessary DOM elements, attach them, and set their, * initial configuration. - * * @param {array} speeds List of speeds available for the player. * @param {string|number} currentSpeed Current speed for the player. - * */ render: function (speeds, currentSpeed) { var self = this, @@ -71,9 +72,8 @@ function (Iterator) { }, /** - * @desc Bind any necessary function callbacks to DOM events (click, - * mousemove, etc.). - * + * Bind any necessary function callbacks to DOM events (click, + * mousemove, etc.). */ bindHandlers: function () { var self = this; @@ -104,18 +104,15 @@ function (Iterator) { }, /** - * @desc Check if playbackRate supports by browser. - * If browser supports, 1.0 should be returned by playbackRate - * property. In this case, function return True. Otherwise, False will - * be returned. - * iOS doesn't support speed change. - * - * @param {string} videoType Type of the video player - * - * @returns {boolean} - * true: Browser support playbackRate functionality. - * false: Browser doesn't support playbackRate functionality. - * + * Check if playbackRate supports by browser. If browser supports, 1.0 + * should be returned by playbackRate property. In this case, function + * return True. Otherwise, False will be returned. + * iOS doesn't support speed change. + * @param {object} state The object containing the state of the video + * player. + * @return {boolean} + * true: Browser support playbackRate functionality. + * false: Browser doesn't support playbackRate functionality. */ isPlaybackRatesSupported: function (state) { var isHtml5 = state.videoType === 'html5', @@ -126,10 +123,8 @@ function (Iterator) { }, /** - * @desc Opens speed menu. - * - * @param {boolean} bindEvent If set, attaches click event on window. - * + * Opens speed menu. + * @param {boolean} [bindEvent] Click event will be attached on window. */ openMenu: function (bindEvent) { // When speed entries have focus, the menu stays open on @@ -145,10 +140,8 @@ function (Iterator) { }, /** - * @desc Closes speed menu. - * - * @param {boolean} unBindEvent If set, detaches click event from window. - * + * Closes speed menu. + * @param {boolean} [unBindEvent] Click event will be detached from window. */ closeMenu: function (unBindEvent) { // Remove the previously added clickHandler from window element. @@ -161,15 +154,13 @@ function (Iterator) { }, /** - * @desc Sets new current speed for the speed control and triggers - * `speedchange` event if needed. - * + * Sets new current speed for the speed control and triggers `speedchange` + * event if needed. * @param {string|number} speed Speed to be set. - * @param {boolean} silent If set, sets new speed without triggering - * `speedchange` event. - * @param {boolean} forceUpdate If set, updates the speed even if it's - * not differs from current speed. - * + * @param {boolean} [silent] Sets the new speed without triggering + * `speedchange` event. + * @param {boolean} [forceUpdate] Updates the speed even if it's + * not differs from current speed. */ setSpeed: function (speed, silent, forceUpdate) { if (speed !== this.currentSpeed || forceUpdate) { @@ -189,10 +180,8 @@ function (Iterator) { }, /** - * @desc Click event handler for the menu. - * + * Click event handler for the menu. * @param {jquery Event} event - * */ clickMenuHandler: function (event) { this.closeMenu(); @@ -201,10 +190,8 @@ function (Iterator) { }, /** - * @desc Click event handler for speed links. - * + * Click event handler for speed links. * @param {jquery Event} event - * */ clickLinkHandler: function (event) { var speed = $(event.currentTarget).parent().data('speed'); @@ -216,10 +203,8 @@ function (Iterator) { }, /** - * @desc Mouseenter event handler for the menu. - * + * Mouseenter event handler for the menu. * @param {jquery Event} event - * */ mouseEnterHandler: function (event) { this.openMenu(); @@ -228,10 +213,8 @@ function (Iterator) { }, /** - * @desc Mouseleave event handler for the menu. - * + * Mouseleave event handler for the menu. * @param {jquery Event} event - * */ mouseLeaveHandler: function (event) { // Only close the menu is no speed entry has focus. @@ -243,10 +226,8 @@ function (Iterator) { }, /** - * @desc Keydown event handler for the menu. - * + * Keydown event handler for the menu. * @param {jquery Event} event - * */ keyDownMenuHandler: function (event) { var KEY = $.ui.keyCode, @@ -271,10 +252,8 @@ function (Iterator) {     }, /** - * @desc Keydown event handler for speed links. - * + * Keydown event handler for speed links. * @param {jquery Event} event - * */ keyDownLinkHandler: function (event) { // ALT key is used to change (alternate) the function of