jquery.spinner: Fix documentation formatting

This syntax is a really fickle beast.

Plus assorted doc fixes.

Change-Id: I1dc2cdc2244db8499bd3f10377b6076955b9765b

diff --git a/resources/jquery/jquery.spinner.js b/resources/jquery/jquery.spinner.js
index 27dabc6..1cd6ff0 100644 (file)
--- a/resources/jquery/jquery.spinner.js
+++ b/resources/jquery/jquery.spinner.js
@@ -19,39 +19,46 @@
                /**
                 * 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
                 *
-                *   // 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:
+                *
+                *     // 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 );
+                *     // 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' });
+                *     // The following two are equivalent:
+                *     $.createSpinner( 'magic' );
+                *     $.createSpinner({ id: 'magic' });
                 *
                 * @static
                 * @inheritable
-                * @param {Object|string} [opts] 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.
+                * @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.
+                *
                 * @return {jQuery}
                 */
                createSpinner: function ( opts ) {
@@ -90,7 +97,7 @@
        /**
         * Inject a spinner after each element in the collection
         *
-        * Inserts spinner as siblings, not children, of the target elements.
+        * Inserts spinner as siblings (not children) of the target elements.
         * Collection contents remain unchanged.
         *
         * @param {Object|string} [opts] See #createSpinner