Merge "jquery.makeCollapsible: Remove useless debug logging"

[lhc/web/wiklou.git] / resources / jquery / jquery.spinner.js

diff --git a/resources/jquery/jquery.spinner.js b/resources/jquery/jquery.spinner.js
index 93e30b9..1cd6ff0 100644 (file)
--- a/resources/jquery/jquery.spinner.js
+++ b/resources/jquery/jquery.spinner.js
@@ -1,7 +1,9 @@
 /**
- * jQuery spinner
+ * jQuery Spinner
  *
  * Simple jQuery plugin to create, inject and remove spinners.
+ *
+ * @class jQuery.plugin.spinner
  */
 ( function ( $ ) {
 
@@ -15,40 +17,48 @@
 
        $.extend({
                /**
-                * Creates a spinner element.
+                * Create a spinner element
                 *
-                * The argument is an object with options used to construct the spinner. These can be:
+                * The argument is an object with options used to construct the spinner (see below).
                 *
-                * It is a good practice to keep a reference to the created spinner to be able to remove it later.
-                * Alternatively one can use the id option and removeSpinner() (but make sure to choose an id
-                * that's unlikely to cause conflicts, e.g. with extensions, gadgets or user scripts).
+                * It is a good practice to keep a reference to the created spinner to be able to remove it
+                * later. Alternatively, one can use the 'id' option and #removeSpinner (but make sure to choose
+                * an id that's unlikely to cause conflicts, e.g. with extensions, gadgets or user scripts).
                 *
                 * CSS classes used:
-                *   .mw-spinner for every spinner
-                *   .mw-spinner-small / .mw-spinner-large for size
-                *   .mw-spinner-block / .mw-spinner-inline for display types
                 *
-                * @example
-                *   // Create a large spinner reserving all available horizontal space.
-                *   var $spinner = $.createSpinner({ size: 'large', type: 'block' });
-                *   // Insert above page content.
-                *   $( '#mw-content-text' ).prepend( $spinner );
-                * @example
-                *   // Place a small inline spinner next to the "Save" button
-                *   var $spinner = $.createSpinner({ size: 'small', type: 'inline' });
-                *   // Alternatively, just `$.createSpinner();` as these are the default options.
-                *   $( '#wpSave' ).after( $spinner );
-                * @example
-                *   // The following two are equivalent:
-                *   $.createSpinner( 'magic' );
-                *   $.createSpinner({ id: 'magic' });
+                * - .mw-spinner for every spinner
+                * - .mw-spinner-small / .mw-spinner-large for size
+                * - .mw-spinner-block / .mw-spinner-inline for display types
+                *
+                * Example:
+                *
+                *     // Create a large spinner reserving all available horizontal space.
+                *     var $spinner = $.createSpinner({ size: 'large', type: 'block' });
+                *     // Insert above page content.
+                *     $( '#mw-content-text' ).prepend( $spinner );
+                *
+                *     // Place a small inline spinner next to the "Save" button
+                *     var $spinner = $.createSpinner({ size: 'small', type: 'inline' });
+                *     // Alternatively, just `$.createSpinner();` as these are the default options.
+                *     $( '#wpSave' ).after( $spinner );
+                *
+                *     // The following two are equivalent:
+                *     $.createSpinner( 'magic' );
+                *     $.createSpinner({ id: 'magic' });
+                *
+                * @static
+                * @inheritable
+                * @param {Object|string} [opts] Options. An object with the following keys:
+                *
+                * - id: If given, spinner will be given an id of "mw-spinner-{id}"
+                * - size: 'small' (default) or 'large' for a 20-pixel or 32-pixel spinner
+                * - type: 'inline' (default) or 'block'. Inline creates an inline-block with width and
+                *   height equal to spinner size. Block is a block-level element with width 100%, height
+                *   equal to spinner size.
+                *
+                * If a string is given, it will be treated as the value of the 'id' option.
                 *
-                * @param {Object|String} opts [optional] ID string or options:
-                *  - id: If given, spinner will be given an id of "mw-spinner-<id>"
-                *  - size: 'small' (default) or 'large' for a 20-pixel or 32-pixel spinner
-                *  - type: 'inline' (default) or 'block'. Inline creates an inline-block with width and
-                *    height equal to spinner size. Block is a block-level element with width 100%, height
-                *    equal to spinner size.
                 * @return {jQuery}
                 */
                createSpinner: function ( opts ) {
@@ -72,10 +82,12 @@
                },
 
                /**
-                * Removes a spinner element.
+                * Remove a spinner element
                 *
-                * @param {String} id [optional] Id of the spinner, as passed to createSpinner.
-                * @return {jQuery} The (now detached) spinner.
+                * @static
+                * @inheritable
+                * @param {string} id Id of the spinner, as passed to #createSpinner
+                * @return {jQuery} The (now detached) spinner element
                 */
                removeSpinner: function ( id ) {
                        return $( '#mw-spinner-' + id ).remove();
@@ -83,13 +95,21 @@
        });
 
        /**
-        * Injects a spinner after the elements in the jQuery collection
-        * (as siblings, not children). Collection contents remain unchanged.
+        * Inject a spinner after each element in the collection
+        *
+        * Inserts spinner as siblings (not children) of the target elements.
+        * Collection contents remain unchanged.
         *
-        * @param {Object|String} opts See createSpinner() for description.
+        * @param {Object|string} [opts] See #createSpinner
         * @return {jQuery}
         */
        $.fn.injectSpinner = function ( opts ) {
                return this.after( $.createSpinner( opts ) );
        };
+
+       /**
+        * @class jQuery
+        * @mixins jQuery.plugin.spinner
+        */
+
 }( jQuery ) );