Commit f33c6be7 authored by catch's avatar catch

Issue #2559697 by theMusician, eiriksm, AjitS, dimaro: JSDoc misc/

parent e08394a6
...@@ -29,6 +29,9 @@ ...@@ -29,6 +29,9 @@
* Builds a div element with the aria-live attribute and add it to the DOM. * Builds a div element with the aria-live attribute and add it to the DOM.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches the behavior for drupalAnnouce.
*/ */
Drupal.behaviors.drupalAnnounce = { Drupal.behaviors.drupalAnnounce = {
attach: function (context) { attach: function (context) {
...@@ -98,6 +101,7 @@ ...@@ -98,6 +101,7 @@
* 'polite' or 'assertive'. * 'polite' or 'assertive'.
* *
* @return {function} * @return {function}
* The return of the call to debounce.
* *
* @see http://www.w3.org/WAI/PF/aria-practices/#liveprops * @see http://www.w3.org/WAI/PF/aria-practices/#liveprops
*/ */
......
...@@ -15,8 +15,10 @@ ...@@ -15,8 +15,10 @@
* @function Drupal.autocomplete.splitValues * @function Drupal.autocomplete.splitValues
* *
* @param {string} value * @param {string} value
* The value being entered by the user.
* *
* @return {Array} * @return {Array}
* Array of values, split by comma.
*/ */
function autocompleteSplitValues(value) { function autocompleteSplitValues(value) {
// We will match the value against comma-separated terms. // We will match the value against comma-separated terms.
...@@ -53,8 +55,10 @@ ...@@ -53,8 +55,10 @@
* @function Drupal.autocomplete.extractLastTerm * @function Drupal.autocomplete.extractLastTerm
* *
* @param {string} terms * @param {string} terms
* The value of the field.
* *
* @return {string} * @return {string}
* The last value of the input field.
*/ */
function extractLastTerm(terms) { function extractLastTerm(terms) {
return autocomplete.splitValues(terms).pop(); return autocomplete.splitValues(terms).pop();
...@@ -66,8 +70,10 @@ ...@@ -66,8 +70,10 @@
* @function Drupal.autocomplete.options.search * @function Drupal.autocomplete.options.search
* *
* @param {object} event * @param {object} event
* The event triggered.
* *
* @return {bool} * @return {bool}
* Whether to perform a search or not.
*/ */
function searchHandler(event) { function searchHandler(event) {
var options = autocomplete.options; var options = autocomplete.options;
...@@ -84,7 +90,9 @@ ...@@ -84,7 +90,9 @@
* JQuery UI autocomplete source callback. * JQuery UI autocomplete source callback.
* *
* @param {object} request * @param {object} request
* The request object.
* @param {function} response * @param {function} response
* The function to call with the response.
*/ */
function sourceData(request, response) { function sourceData(request, response) {
var elementId = this.element.attr('id'); var elementId = this.element.attr('id');
...@@ -98,6 +106,7 @@ ...@@ -98,6 +106,7 @@
* display the available terms to the user. * display the available terms to the user.
* *
* @param {object} suggestions * @param {object} suggestions
* Suggestions returned by the server.
*/ */
function showSuggestions(suggestions) { function showSuggestions(suggestions) {
var tagged = autocomplete.splitValues(request.term); var tagged = autocomplete.splitValues(request.term);
...@@ -115,6 +124,7 @@ ...@@ -115,6 +124,7 @@
* Transforms the data object into an array and update autocomplete results. * Transforms the data object into an array and update autocomplete results.
* *
* @param {object} data * @param {object} data
* The data sent back from the server.
*/ */
function sourceCallbackHandler(data) { function sourceCallbackHandler(data) {
autocomplete.cache[elementId][term] = data; autocomplete.cache[elementId][term] = data;
...@@ -140,6 +150,7 @@ ...@@ -140,6 +150,7 @@
* Handles an autocompletefocus event. * Handles an autocompletefocus event.
* *
* @return {bool} * @return {bool}
* Always returns false.
*/ */
function focusHandler() { function focusHandler() {
return false; return false;
...@@ -149,9 +160,12 @@ ...@@ -149,9 +160,12 @@
* Handles an autocompleteselect event. * Handles an autocompleteselect event.
* *
* @param {jQuery.Event} event * @param {jQuery.Event} event
* The event triggered.
* @param {object} ui * @param {object} ui
* The jQuery UI settings object.
* *
* @return {bool} * @return {bool}
* Returns false to indicate the event status.
*/ */
function selectHandler(event, ui) { function selectHandler(event, ui) {
var terms = autocomplete.splitValues(event.target.value); var terms = autocomplete.splitValues(event.target.value);
...@@ -172,10 +186,13 @@ ...@@ -172,10 +186,13 @@
/** /**
* Override jQuery UI _renderItem function to output HTML by default. * Override jQuery UI _renderItem function to output HTML by default.
* *
* @param {object} ul * @param {jQuery} ul
* jQuery collection of the ul element.
* @param {object} item * @param {object} item
* The list item to append.
* *
* @return {object} * @return {jQuery}
* jQuery collection of the ul element.
*/ */
function renderItem(ul, item) { function renderItem(ul, item) {
return $('<li>') return $('<li>')
...@@ -187,6 +204,11 @@ ...@@ -187,6 +204,11 @@
* Attaches the autocomplete behavior to all required fields. * Attaches the autocomplete behavior to all required fields.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches the autocomplete behaviors.
* @prop {Drupal~behaviorDetach} detach
* Detaches the autocomplete behaviors.
*/ */
Drupal.behaviors.autocomplete = { Drupal.behaviors.autocomplete = {
attach: function (context) { attach: function (context) {
......
...@@ -13,6 +13,7 @@ ...@@ -13,6 +13,7 @@
* @constructor Drupal.CollapsibleDetails * @constructor Drupal.CollapsibleDetails
* *
* @param {HTMLElement} node * @param {HTMLElement} node
* The details element.
*/ */
function CollapsibleDetails(node) { function CollapsibleDetails(node) {
this.$node = $(node); this.$node = $(node);
...@@ -82,6 +83,7 @@ ...@@ -82,6 +83,7 @@
* Handle legend clicks. * Handle legend clicks.
* *
* @param {jQuery.Event} e * @param {jQuery.Event} e
* The event triggered.
*/ */
onLegendClick: function (e) { onLegendClick: function (e) {
this.toggle(); this.toggle();
...@@ -120,6 +122,9 @@ ...@@ -120,6 +122,9 @@
* Polyfill HTML5 details element. * Polyfill HTML5 details element.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches behavior for the details element.
*/ */
Drupal.behaviors.collapse = { Drupal.behaviors.collapse = {
attach: function (context) { attach: function (context) {
......
...@@ -11,6 +11,9 @@ ...@@ -11,6 +11,9 @@
* Initialize dialogs for Ajax purposes. * Initialize dialogs for Ajax purposes.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches the behaviors for dialog ajax functionality.
*/ */
Drupal.behaviors.dialog = { Drupal.behaviors.dialog = {
attach: function (context, settings) { attach: function (context, settings) {
...@@ -90,10 +93,14 @@ ...@@ -90,10 +93,14 @@
* Command to open a dialog. * Command to open a dialog.
* *
* @param {Drupal.Ajax} ajax * @param {Drupal.Ajax} ajax
* The Drupal Ajax object.
* @param {object} response * @param {object} response
* Object holding the server response.
* @param {number} [status] * @param {number} [status]
* The HTTP status code.
* *
* @return {bool|undefined} * @return {bool|undefined}
* Returns false if there was no selector property in the response object.
*/ */
Drupal.AjaxCommands.prototype.openDialog = function (ajax, response, status) { Drupal.AjaxCommands.prototype.openDialog = function (ajax, response, status) {
if (!response.selector) { if (!response.selector) {
...@@ -146,10 +153,15 @@ ...@@ -146,10 +153,15 @@
* If no selector is given, it defaults to trying to close the modal. * If no selector is given, it defaults to trying to close the modal.
* *
* @param {Drupal.Ajax} [ajax] * @param {Drupal.Ajax} [ajax]
* The ajax object.
* @param {object} response * @param {object} response
* Object holding the server response.
* @param {string} response.selector * @param {string} response.selector
* The selector of the dialog.
* @param {bool} response.persist * @param {bool} response.persist
* Whether to persist the dialog element or not.
* @param {number} [status] * @param {number} [status]
* The HTTP status code.
*/ */
Drupal.AjaxCommands.prototype.closeDialog = function (ajax, response, status) { Drupal.AjaxCommands.prototype.closeDialog = function (ajax, response, status) {
var $dialog = $(response.selector); var $dialog = $(response.selector);
...@@ -170,11 +182,17 @@ ...@@ -170,11 +182,17 @@
* JQuery UI specific way of setting dialog options. * JQuery UI specific way of setting dialog options.
* *
* @param {Drupal.Ajax} [ajax] * @param {Drupal.Ajax} [ajax]
* The Drupal Ajax object.
* @param {object} response * @param {object} response
* Object holding the server response.
* @param {string} response.selector * @param {string} response.selector
* Selector for the dialog element.
* @param {string} response.optionsName * @param {string} response.optionsName
* Name of a key to set.
* @param {string} response.optionValue * @param {string} response.optionValue
* Value to set.
* @param {number} [status] * @param {number} [status]
* The HTTP status code.
*/ */
Drupal.AjaxCommands.prototype.setDialogOption = function (ajax, response, status) { Drupal.AjaxCommands.prototype.setDialogOption = function (ajax, response, status) {
var $dialog = $(response.selector); var $dialog = $(response.selector);
...@@ -187,9 +205,13 @@ ...@@ -187,9 +205,13 @@
* Binds a listener on dialog creation to handle the cancel link. * Binds a listener on dialog creation to handle the cancel link.
* *
* @param {jQuery.Event} e * @param {jQuery.Event} e
* The event triggered.
* @param {Drupal.dialog~dialogDefinition} dialog * @param {Drupal.dialog~dialogDefinition} dialog
* The dialog instance.
* @param {jQuery} $element * @param {jQuery} $element
* @param {object} settings * The jQuery collection of the dialog element.
* @param {object} [settings]
* Dialog settings.
*/ */
$(window).on('dialog:aftercreate', function (e, dialog, $element, settings) { $(window).on('dialog:aftercreate', function (e, dialog, $element, settings) {
$element.on('click.dialog', '.dialog-cancel', function (e) { $element.on('click.dialog', '.dialog-cancel', function (e) {
...@@ -203,8 +225,11 @@ ...@@ -203,8 +225,11 @@
* Removes all 'dialog' listeners. * Removes all 'dialog' listeners.
* *
* @param {jQuery.Event} e * @param {jQuery.Event} e
* The event triggered.
* @param {Drupal.dialog~dialogDefinition} dialog * @param {Drupal.dialog~dialogDefinition} dialog
* The dialog instance.
* @param {jQuery} $element * @param {jQuery} $element
* jQuery collection of the dialog element.
*/ */
$(window).on('dialog:beforeclose', function (e, dialog, $element) { $(window).on('dialog:beforeclose', function (e, dialog, $element) {
$element.off('.dialog'); $element.off('.dialog');
......
...@@ -55,10 +55,12 @@ ...@@ -55,10 +55,12 @@
* Polyfill HTML5 dialog element with jQueryUI. * Polyfill HTML5 dialog element with jQueryUI.
* *
* @param {HTMLElement} element * @param {HTMLElement} element
* The element that holds the dialog.
* @param {object} options * @param {object} options
* jQuery UI options to be passed to the dialog. * jQuery UI options to be passed to the dialog.
* *
* @return {Drupal.dialog~dialogDefinition} * @return {Drupal.dialog~dialogDefinition}
* The dialog instance.
*/ */
Drupal.dialog = function (element, options) { Drupal.dialog = function (element, options) {
var undef; var undef;
......
...@@ -27,6 +27,7 @@ ...@@ -27,6 +27,7 @@
* @function Drupal.dialog~resetSize * @function Drupal.dialog~resetSize
* *
* @param {jQuery.Event} event * @param {jQuery.Event} event
* The event triggered.
* *
* @fires event:dialogContentResize * @fires event:dialogContentResize
*/ */
...@@ -67,8 +68,10 @@ ...@@ -67,8 +68,10 @@
* @function Drupal.dialog~resetPosition * @function Drupal.dialog~resetPosition
* *
* @param {object} options * @param {object} options
* Options object.
* *
* @return {object} * @return {object}
* Altered options object.
*/ */
function resetPosition(options) { function resetPosition(options) {
var offsets = displace.offsets; var offsets = displace.offsets;
......
...@@ -11,6 +11,9 @@ ...@@ -11,6 +11,9 @@
* Process elements with the .dropbutton class on page load. * Process elements with the .dropbutton class on page load.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches dropButton behaviors.
*/ */
Drupal.behaviors.dropButton = { Drupal.behaviors.dropButton = {
attach: function (context, settings) { attach: function (context, settings) {
...@@ -36,6 +39,7 @@ ...@@ -36,6 +39,7 @@
* @function Drupal.DropButton~dropbuttonClickHandler * @function Drupal.DropButton~dropbuttonClickHandler
* *
* @param {jQuery.Event} e * @param {jQuery.Event} e
* The event triggered.
*/ */
function dropbuttonClickHandler(e) { function dropbuttonClickHandler(e) {
e.preventDefault(); e.preventDefault();
...@@ -190,6 +194,7 @@ ...@@ -190,6 +194,7 @@
/** /**
* @param {jQuery.Event} e * @param {jQuery.Event} e
* The event triggered.
*/ */
focusOut: function (e) { focusOut: function (e) {
this.hoverOut.call(this, e); this.hoverOut.call(this, e);
...@@ -197,6 +202,7 @@ ...@@ -197,6 +202,7 @@
/** /**
* @param {jQuery.Event} e * @param {jQuery.Event} e
* The event triggered.
*/ */
focusIn: function (e) { focusIn: function (e) {
this.hoverIn.call(this, e); this.hoverIn.call(this, e);
...@@ -209,6 +215,7 @@ ...@@ -209,6 +215,7 @@
* A toggle is an interactive element often bound to a click handler. * A toggle is an interactive element often bound to a click handler.
* *
* @param {object} options * @param {object} options
* Options object.
* @param {string} [options.title] * @param {string} [options.title]
* The HTML anchor title attribute and text for the inner span element. * The HTML anchor title attribute and text for the inner span element.
* *
......
...@@ -273,6 +273,7 @@ if (window.jQuery) { ...@@ -273,6 +273,7 @@ if (window.jQuery) {
* `{@link Drupal.theme}('placeholder')`). * `{@link Drupal.theme}('placeholder')`).
* *
* @return {string} * @return {string}
* The formatted string.
* *
* @see Drupal.t * @see Drupal.t
*/ */
......
...@@ -20,6 +20,7 @@ ...@@ -20,6 +20,7 @@
* Retrieves the summary for the first element. * Retrieves the summary for the first element.
* *
* @return {string} * @return {string}
* The text of the summary.
*/ */
$.fn.drupalGetSummary = function () { $.fn.drupalGetSummary = function () {
var callback = this.data('summaryCallback'); var callback = this.data('summaryCallback');
...@@ -34,6 +35,7 @@ ...@@ -34,6 +35,7 @@
* retrieved or a string (which is returned each time). * retrieved or a string (which is returned each time).
* *
* @return {jQuery} * @return {jQuery}
* jQuery collection of the current element.
* *
* @fires event:summaryUpdated * @fires event:summaryUpdated
* *
...@@ -125,6 +127,7 @@ ...@@ -125,6 +127,7 @@
* Sends a 'formUpdated' event each time a form element is modified. * Sends a 'formUpdated' event each time a form element is modified.
* *
* @param {HTMLElement} element * @param {HTMLElement} element
* The element to trigger a form updated event on.
* *
* @fires event:formUpdated * @fires event:formUpdated
*/ */
...@@ -136,8 +139,10 @@ ...@@ -136,8 +139,10 @@
* Collects the IDs of all form fields in the given form. * Collects the IDs of all form fields in the given form.
* *
* @param {HTMLFormElement} form * @param {HTMLFormElement} form
* The form element to search.
* *
* @return {Array} * @return {Array}
* Array of IDs for form fields.
*/ */
function fieldsList(form) { function fieldsList(form) {
var $fieldList = $(form).find('[name]').map(function (index, element) { var $fieldList = $(form).find('[name]').map(function (index, element) {
...@@ -154,6 +159,11 @@ ...@@ -154,6 +159,11 @@
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
* *
* @prop {Drupal~behaviorAttach} attach
* Attaches formUpdated behaviors.
* @prop {Drupal~behaviorDetach} detach
* Detaches formUpdated behaviors.
*
* @fires event:formUpdated * @fires event:formUpdated
*/ */
Drupal.behaviors.formUpdated = { Drupal.behaviors.formUpdated = {
...@@ -208,6 +218,9 @@ ...@@ -208,6 +218,9 @@
* Prepopulate form fields with information from the visitor browser. * Prepopulate form fields with information from the visitor browser.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches the behavior for filling user info from browser.
*/ */
Drupal.behaviors.fillUserInfoFromBrowser = { Drupal.behaviors.fillUserInfoFromBrowser = {
attach: function (context, settings) { attach: function (context, settings) {
......
...@@ -11,6 +11,9 @@ ...@@ -11,6 +11,9 @@
* Attach the machine-readable name form element behavior. * Attach the machine-readable name form element behavior.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches machine-name behaviors.
*/ */
Drupal.behaviors.machineName = { Drupal.behaviors.machineName = {
...@@ -18,7 +21,9 @@ ...@@ -18,7 +21,9 @@
* Attaches the behavior. * Attaches the behavior.
* *
* @param {Element} context * @param {Element} context
* The context for attaching the behavior.
* @param {object} settings * @param {object} settings
* Settings object.
* @param {object} settings.machineName * @param {object} settings.machineName
* A list of elements to process, keyed by the HTML ID of the form * A list of elements to process, keyed by the HTML ID of the form
* element containing the human-readable value. Each element is an object * element containing the human-readable value. Each element is an object
......
...@@ -11,6 +11,7 @@ ...@@ -11,6 +11,7 @@
* Theme function for the progress bar. * Theme function for the progress bar.
* *
* @param {string} id * @param {string} id
* The id for the progress bar.
* *
* @return {string} * @return {string}
* The HTML for the progress bar. * The HTML for the progress bar.
...@@ -38,9 +39,13 @@ ...@@ -38,9 +39,13 @@
* @constructor * @constructor
* *
* @param {string} id * @param {string} id
* The id for the progressbar.
* @param {function} updateCallback * @param {function} updateCallback
* Callback to run on update.
* @param {string} method * @param {string} method
* HTTP method to use.
* @param {function} errorCallback * @param {function} errorCallback
* Callback to call on error.
*/ */
Drupal.ProgressBar = function (id, updateCallback, method, errorCallback) { Drupal.ProgressBar = function (id, updateCallback, method, errorCallback) {
this.id = id; this.id = id;
...@@ -61,8 +66,11 @@ ...@@ -61,8 +66,11 @@
* Set the percentage and status message for the progressbar. * Set the percentage and status message for the progressbar.
* *
* @param {number} percentage * @param {number} percentage
* The progress percentage.
* @param {string} message * @param {string} message
* The message to show the user.
* @param {string} label * @param {string} label
* The text for the progressbar label.
*/ */
setProgress: function (percentage, message, label) { setProgress: function (percentage, message, label) {
if (percentage >= 0 && percentage <= 100) { if (percentage >= 0 && percentage <= 100) {
...@@ -80,7 +88,9 @@ ...@@ -80,7 +88,9 @@
* Start monitoring progress via Ajax. * Start monitoring progress via Ajax.
* *
* @param {string} uri * @param {string} uri
* The URI to use for monitoring.
* @param {number} delay * @param {number} delay
* The delay for calling the monitoring URI.
*/ */
startMonitoring: function (uri, delay) { startMonitoring: function (uri, delay) {
this.delay = delay; this.delay = delay;
...@@ -144,6 +154,7 @@ ...@@ -144,6 +154,7 @@
* Display errors on the page. * Display errors on the page.
* *
* @param {string} string * @param {string} string
* The error message to show the user.
*/ */
displayError: function (string) { displayError: function (string) {
var error = $('<div class="messages messages--error"></div>').html(string); var error = $('<div class="messages messages--error"></div>').html(string);
......
...@@ -27,6 +27,9 @@ ...@@ -27,6 +27,9 @@
* Attaches the states. * Attaches the states.
* *
* @type {Drupal~behavior} * @type {Drupal~behavior}
*
* @prop {Drupal~behaviorAttach} attach
* Attaches states behaviors.
*/ */
Drupal.behaviors.states = { Drupal.behaviors.states = {
attach: function (context, settings) { attach: function (context, settings) {
...@@ -329,6 +332,7 @@ ...@@ -329,6 +332,7 @@
* @memberof Drupal.states.Dependent# * @memberof Drupal.states.Dependent#
* *
* @return {object} * @return {object}
* An object describing the required triggers.
*/ */
getDependees: function () { getDependees: function () {
var cache = {}; var cache = {};
...@@ -359,6 +363,7 @@ ...@@ -359,6 +363,7 @@
* @constructor Drupal.states.Trigger * @constructor Drupal.states.Trigger
* *
* @param {object} args * @param {object} args
* Trigger arguments.
*/ */
states.Trigger = function (args) { states.Trigger = function (args) {
$.extend(this, args); $.extend(this, args);
...@@ -402,7 +407,9 @@ ...@@ -402,7 +407,9 @@
* @memberof Drupal.states.Trigger# * @memberof Drupal.states.Trigger#
* *
* @param {jQuery.Event} event * @param {jQuery.Event} event
* The event triggered.
* @param {function} valueFn * @param {function} valueFn
* The function to call.
*/ */
defaultTrigger: function (event, valueFn) { defaultTrigger: function (event, valueFn) {
var oldValue = valueFn.call(this.element); var oldValue = valueFn.call(this.element);
...@@ -498,6 +505,7 @@ ...@@ -498,6 +505,7 @@
* @constructor Drupal.states.State * @constructor Drupal.states.State
* *
* @param {string} state * @param {string} state
* The name of the state.
*/ */
states.State = function (state) { states.State = function (state) {
...@@ -531,8 +539,10 @@ ...@@ -531,8 +539,10 @@
* @name Drupal.states.State.sanitize * @name Drupal.states.State.sanitize
* *
* @param {string|Drupal.states.State} state * @param {string|Drupal.states.State} state
* A state object or the name of a state.
* *
* @return {Drupal.states.state} * @return {Drupal.states.state}
* A state object.
*/ */
states.State.sanitize = function (state) { states.State.sanitize = function (state) {
if (state instanceof states.State) { if (state instanceof states.State) {
...@@ -577,6 +587,7 @@ ...@@ -577,6 +587,7 @@