From d837f119c3729565103005d5d7fa89e1dd8110cb Mon Sep 17 00:00:00 2001 From: Dave Methvin Date: Fri, 25 Apr 2014 18:26:36 -0400 Subject: [PATCH] Support: clean up comments and Support notation Closes gh-1577 --- src/ajax.js | 11 ++++--- src/attributes/attr.js | 2 -- src/attributes/classes.js | 8 ++--- src/attributes/prop.js | 4 +-- src/attributes/support.js | 16 +++++----- src/attributes/val.js | 8 ++--- src/core.js | 10 +++---- src/core/init.js | 6 ++-- src/core/ready.js | 2 +- src/css.js | 57 ++++++++++++++++++----------------- src/css/addGetHookIf.js | 6 ++-- src/css/curCSS.js | 2 +- src/css/defaultDisplay.js | 2 +- src/css/support.js | 4 +++ src/data.js | 21 +++++++------ src/data/Data.js | 4 +-- src/deferred.js | 4 +-- src/dimensions.js | 2 +- src/effects.js | 59 ++++++++++++++++++------------------- src/effects/Tween.js | 14 ++++----- src/event.js | 10 +++---- src/exports/global.js | 4 +-- src/intro.js | 16 +++++----- src/manipulation.js | 20 ++++++------- src/manipulation/support.js | 11 +++---- src/offset.js | 15 ++++++---- src/queue.js | 6 ++-- src/traversing.js | 7 ++--- 28 files changed, 161 insertions(+), 170 deletions(-) diff --git a/src/ajax.js b/src/ajax.js index 0d0644b92..ea808716d 100644 --- a/src/ajax.js +++ b/src/ajax.js @@ -44,8 +44,8 @@ var // Avoid comment-prolog char sequence (#10098); must appease lint and evade compression allTypes = "*/".concat("*"); -// #8138, IE may throw an exception when accessing -// a field from window.location if document.domain has been set +// Support: IE6 +// Exception accessing window.location.href if document.domain is set (#8138) try { ajaxLocation = location.href; } catch( e ) { @@ -610,7 +610,7 @@ jQuery.extend({ return jqXHR.abort(); } - // aborting is no longer a cancellation + // Aborting is no longer a cancellation strAbort = "abort"; // Install callbacks on deferreds @@ -722,8 +722,7 @@ jQuery.extend({ isSuccess = !error; } } else { - // We extract error from statusText - // then normalize statusText and status for non-aborts + // Extract error from statusText and normalize for non-aborts error = statusText; if ( status || !statusText ) { statusText = "error"; @@ -779,7 +778,7 @@ jQuery.extend({ jQuery.each( [ "get", "post" ], function( i, method ) { jQuery[ method ] = function( url, data, callback, type ) { - // shift arguments if data argument was omitted + // Shift arguments if data argument was omitted if ( jQuery.isFunction( data ) ) { type = type || callback; callback = data; diff --git a/src/attributes/attr.js b/src/attributes/attr.js index 8601cfe11..a4414d11f 100644 --- a/src/attributes/attr.js +++ b/src/attributes/attr.js @@ -96,8 +96,6 @@ jQuery.extend({ set: function( elem, value ) { if ( !support.radioValue && value === "radio" && jQuery.nodeName( elem, "input" ) ) { - // Setting the type on a radio button after the value resets the value in IE6-9 - // Reset value to default in case type is set after value during creation var val = elem.value; elem.setAttribute( "type", value ); if ( val ) { diff --git a/src/attributes/classes.js b/src/attributes/classes.js index 7d714b8e1..101138415 100644 --- a/src/attributes/classes.js +++ b/src/attributes/classes.js @@ -83,7 +83,7 @@ jQuery.fn.extend({ } } - // only assign if different to avoid unneeded rendering. + // Only assign if different to avoid unneeded rendering. finalValue = value ? jQuery.trim( cur ) : ""; if ( elem.className !== finalValue ) { elem.className = finalValue; @@ -110,14 +110,14 @@ jQuery.fn.extend({ return this.each(function() { if ( type === "string" ) { - // toggle individual class names + // Toggle individual class names var className, i = 0, self = jQuery( this ), classNames = value.match( rnotwhite ) || []; while ( (className = classNames[ i++ ]) ) { - // check each className given, space separated list + // Check each className given, space separated list if ( self.hasClass( className ) ) { self.removeClass( className ); } else { @@ -132,7 +132,7 @@ jQuery.fn.extend({ data_priv.set( this, "__className__", this.className ); } - // If the element has a class name or if we're passed "false", + // If the element has a class name or if we're passed `false`, // then remove the whole classname (if there was one, the above saved it). // Otherwise bring back whatever was previously saved (if anything), // falling back to the empty string if nothing was stored. diff --git a/src/attributes/prop.js b/src/attributes/prop.js index e2b95dcab..d4ee8b6b9 100644 --- a/src/attributes/prop.js +++ b/src/attributes/prop.js @@ -28,7 +28,7 @@ jQuery.extend({ var ret, hooks, notxml, nType = elem.nodeType; - // don't get/set properties on text, comment and attribute nodes + // Don't get/set properties on text, comment and attribute nodes if ( !elem || nType === 3 || nType === 8 || nType === 2 ) { return; } @@ -64,8 +64,6 @@ jQuery.extend({ } }); -// Support: IE9+ -// Selectedness for an option in an optgroup can be inaccurate if ( !support.optSelected ) { jQuery.propHooks.selected = { get: function( elem ) { diff --git a/src/attributes/support.js b/src/attributes/support.js index 376b54ad2..5db5c5212 100644 --- a/src/attributes/support.js +++ b/src/attributes/support.js @@ -9,21 +9,21 @@ define([ input.type = "checkbox"; - // Support: iOS 5.1, Android 4.x, Android 2.3 - // Check the default checkbox/radio value ("" on old WebKit; "on" elsewhere) + // Support: iOS<=5.1, Android<=4.2+ + // Default value for a checkbox should be "on" support.checkOn = input.value !== ""; - // Must access the parent to make an option select properly - // Support: IE9, IE10 + // Support: IE<=11+ + // Must access selectedIndex to make default options select support.optSelected = opt.selected; - // Make sure that the options inside disabled selects aren't marked as disabled - // (WebKit marks them as disabled) + // Support: Android<=2.3 + // Options inside disabled selects are incorrectly marked as disabled select.disabled = true; support.optDisabled = !opt.disabled; - // Check if an input maintains its value after becoming a radio - // Support: IE9, IE10 + // Support: IE<=11+ + // An input loses its value after becoming a radio input = document.createElement( "input" ); input.value = "t"; input.type = "radio"; diff --git a/src/attributes/val.js b/src/attributes/val.js index 42ef32343..4a1358a65 100644 --- a/src/attributes/val.js +++ b/src/attributes/val.js @@ -22,9 +22,9 @@ jQuery.fn.extend({ ret = elem.value; return typeof ret === "string" ? - // handle most common string cases + // Handle most common string cases ret.replace(rreturn, "") : - // handle cases where value is null/undef or number + // Handle cases where value is null/undef or number ret == null ? "" : ret; } @@ -132,7 +132,7 @@ jQuery.extend({ } } - // force browsers to behave consistently when non-matching value is set + // Force browsers to behave consistently when non-matching value is set if ( !optionSet ) { elem.selectedIndex = -1; } @@ -153,8 +153,6 @@ jQuery.each([ "radio", "checkbox" ], function() { }; if ( !support.checkOn ) { jQuery.valHooks[ this ].get = function( elem ) { - // Support: Webkit - // "" is returned instead of "on" if a value isn't specified return elem.getAttribute("value") === null ? "on" : elem.value; }; } diff --git a/src/core.js b/src/core.js index d4c3bce3c..da6aa833a 100644 --- a/src/core.js +++ b/src/core.js @@ -132,7 +132,7 @@ jQuery.extend = jQuery.fn.extend = function() { if ( typeof target === "boolean" ) { deep = target; - // skip the boolean and the target + // Skip the boolean and the target target = arguments[ i ] || {}; i++; } @@ -142,7 +142,7 @@ jQuery.extend = jQuery.fn.extend = function() { target = {}; } - // extend jQuery itself if only one argument is passed + // Extend jQuery itself if only one argument is passed if ( i === length ) { target = this; i--; @@ -199,9 +199,6 @@ jQuery.extend({ noop: function() {}, - // See test/unit/core.js for details concerning isFunction. - // Since version 1.3, DOM methods and functions like alert - // aren't supported. They return false on IE (#2968). isFunction: function( obj ) { return jQuery.type(obj) === "function"; }, @@ -251,7 +248,7 @@ jQuery.extend({ if ( obj == null ) { return obj + ""; } - // Support: Android < 4.0, iOS < 6 (functionish RegExp) + // Support: Android<4.0, iOS<6 (functionish RegExp) return typeof obj === "object" || typeof obj === "function" ? class2type[ toString.call(obj) ] || "object" : typeof obj; @@ -281,6 +278,7 @@ jQuery.extend({ }, // Convert dashed to camelCase; used by the css and data modules + // Support: IE9-11+ // Microsoft forgot to hump their vendor prefix (#9572) camelCase: function( string ) { return string.replace( rmsPrefix, "ms-" ).replace( rdashAlpha, fcamelCase ); diff --git a/src/core/init.js b/src/core/init.js index daf5d1909..7e83a0496 100644 --- a/src/core/init.js +++ b/src/core/init.js @@ -38,7 +38,7 @@ var rootjQuery, if ( match[1] ) { context = context instanceof jQuery ? context[0] : context; - // scripts is true for back-compat + // Option to run scripts is true for back-compat // Intentionally let the error be thrown if parseHTML is not present jQuery.merge( this, jQuery.parseHTML( match[1], @@ -66,8 +66,8 @@ var rootjQuery, } else { elem = document.getElementById( match[2] ); - // Check parentNode to catch when Blackberry 4.6 returns - // nodes that are no longer in the document #6963 + // Support: Blackberry 4.6 + // gEBID returns nodes no longer in the document (#6963) if ( elem && elem.parentNode ) { // Inject the element directly into the jQuery object this.length = 1; diff --git a/src/core/ready.js b/src/core/ready.js index 122b1610d..db1a6e60a 100644 --- a/src/core/ready.js +++ b/src/core/ready.js @@ -73,7 +73,7 @@ jQuery.ready.promise = function( obj ) { readyList = jQuery.Deferred(); // Catch cases where $(document).ready() is called after the browser event has already occurred. - // we once tried to use readyState "interactive" here, but it caused issues like the one + // We once tried to use readyState "interactive" here, but it caused issues like the one // discovered by ChrisS here: http://bugs.jquery.com/ticket/12282#comment:15 if ( document.readyState === "complete" ) { // Handle it asynchronously to allow scripts the opportunity to delay ready diff --git a/src/css.js b/src/css.js index 6c20b32df..d4816175d 100644 --- a/src/css.js +++ b/src/css.js @@ -21,8 +21,8 @@ define([ getStyles, curCSS, defaultDisplay, addGetHookIf, support, data_priv ) { var - // swappable if display is none or starts with table except "table", "table-cell", or "table-caption" - // see here for display values: https://developer.mozilla.org/en-US/docs/CSS/display + // Swappable if display is none or starts with table except "table", "table-cell", or "table-caption" + // See here for display values: https://developer.mozilla.org/en-US/docs/CSS/display rdisplayswap = /^(none|table(?!-c[ea]).+)/, rnumsplit = new RegExp( "^(" + pnum + ")(.*)$", "i" ), rrelNum = new RegExp( "^([+-])=(" + pnum + ")", "i" ), @@ -35,15 +35,15 @@ var cssPrefixes = [ "Webkit", "O", "Moz", "ms" ]; -// return a css property mapped to a potentially vendor prefixed property +// Return a css property mapped to a potentially vendor prefixed property function vendorPropName( style, name ) { - // shortcut for names that are not vendor prefixed + // Shortcut for names that are not vendor prefixed if ( name in style ) { return name; } - // check for vendor prefixed names + // Check for vendor prefixed names var capName = name[0].toUpperCase() + name.slice(1), origName = name, i = cssPrefixes.length; @@ -76,7 +76,7 @@ function augmentWidthOrHeight( elem, name, extra, isBorderBox, styles ) { val = 0; for ( ; i < 4; i += 2 ) { - // both box models exclude margin, so add it if we want it + // Both box models exclude margin, so add it if we want it if ( extra === "margin" ) { val += jQuery.css( elem, extra + cssExpand[ i ], true, styles ); } @@ -87,15 +87,15 @@ function augmentWidthOrHeight( elem, name, extra, isBorderBox, styles ) { val -= jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); } - // at this point, extra isn't border nor margin, so remove border + // At this point, extra isn't border nor margin, so remove border if ( extra !== "margin" ) { val -= jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); } } else { - // at this point, extra isn't content, so add padding + // At this point, extra isn't content, so add padding val += jQuery.css( elem, "padding" + cssExpand[ i ], true, styles ); - // at this point, extra isn't content nor padding, so add border + // At this point, extra isn't content nor padding, so add border if ( extra !== "padding" ) { val += jQuery.css( elem, "border" + cssExpand[ i ] + "Width", true, styles ); } @@ -113,7 +113,7 @@ function getWidthOrHeight( elem, name, extra ) { styles = getStyles( elem ), isBorderBox = jQuery.css( elem, "boxSizing", false, styles ) === "border-box"; - // some non-html elements return undefined for offsetWidth, so check for null/undefined + // Some non-html elements return undefined for offsetWidth, so check for null/undefined // svg - https://bugzilla.mozilla.org/show_bug.cgi?id=649285 // MathML - https://bugzilla.mozilla.org/show_bug.cgi?id=491668 if ( val <= 0 || val == null ) { @@ -128,7 +128,7 @@ function getWidthOrHeight( elem, name, extra ) { return val; } - // we need the check for style in case a browser which returns unreliable values + // Check for style in case a browser which returns unreliable values // for getComputedStyle silently falls back to the reliable elem.style valueIsBorderBox = isBorderBox && ( support.boxSizingReliable() || val === elem.style[ name ] ); @@ -137,7 +137,7 @@ function getWidthOrHeight( elem, name, extra ) { val = parseFloat( val ) || 0; } - // use the active box-sizing model to add/subtract irrelevant styles + // Use the active box-sizing model to add/subtract irrelevant styles return ( val + augmentWidthOrHeight( elem, @@ -201,12 +201,14 @@ function showHide( elements, show ) { } jQuery.extend({ + // Add in style property hooks for overriding the default // behavior of getting and setting a style property cssHooks: { opacity: { get: function( elem, computed ) { if ( computed ) { + // We should always get a number back from opacity var ret = curCSS( elem, "opacity" ); return ret === "" ? "1" : ret; @@ -234,12 +236,12 @@ jQuery.extend({ // Add in properties whose names you wish to fix before // setting or getting the value cssProps: { - // normalize float css property "float": "cssFloat" }, // Get and set the style property on a DOM Node style: function( elem, name, value, extra ) { + // Don't set styles on text and comment nodes if ( !elem || elem.nodeType === 3 || elem.nodeType === 8 || !elem.style ) { return; @@ -252,33 +254,32 @@ jQuery.extend({ name = jQuery.cssProps[ origName ] || ( jQuery.cssProps[ origName ] = vendorPropName( style, origName ) ); - // gets hook for the prefixed version - // followed by the unprefixed version + // Gets hook for the prefixed version, then unprefixed version hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; // Check if we're setting a value if ( value !== undefined ) { type = typeof value; - // convert relative number strings (+= or -=) to relative numbers. #7345 + // Convert "+=" or "-=" to relative numbers (#7345) if ( type === "string" && (ret = rrelNum.exec( value )) ) { value = ( ret[1] + 1 ) * ret[2] + parseFloat( jQuery.css( elem, name ) ); // Fixes bug #9237 type = "number"; } - // Make sure that null and NaN values aren't set. See: #7116 + // Make sure that null and NaN values aren't set (#7116) if ( value == null || value !== value ) { return; } - // If a number was passed in, add 'px' to the (except for certain CSS properties) + // If a number, add 'px' to the (except for certain CSS properties) if ( type === "number" && !jQuery.cssNumber[ origName ] ) { value += "px"; } - // Fixes #8908, it can be done more correctly by specifying setters in cssHooks, - // but it would mean to define eight (for every problematic property) identical functions + // Support: IE9-11+ + // background-* props affect original clone's values if ( !support.clearCloneStyle && value === "" && name.indexOf( "background" ) === 0 ) { style[ name ] = "inherit"; } @@ -306,8 +307,7 @@ jQuery.extend({ // Make sure that we're working with the right name name = jQuery.cssProps[ origName ] || ( jQuery.cssProps[ origName ] = vendorPropName( elem.style, origName ) ); - // gets hook for the prefixed version - // followed by the unprefixed version + // Try prefixed name followed by the unprefixed name hooks = jQuery.cssHooks[ name ] || jQuery.cssHooks[ origName ]; // If a hook was provided get the computed value from there @@ -320,12 +320,12 @@ jQuery.extend({ val = curCSS( elem, name, styles ); } - //convert "normal" to computed value + // Convert "normal" to computed value if ( val === "normal" && name in cssNormalTransform ) { val = cssNormalTransform[ name ]; } - // Return, converting to number if forced or a qualifier was provided and val looks numeric + // Make numeric if forced or a qualifier was provided and val looks numeric if ( extra === "" || extra ) { num = parseFloat( val ); return extra === true || jQuery.isNumeric( num ) ? num || 0 : val; @@ -338,8 +338,9 @@ jQuery.each([ "height", "width" ], function( i, name ) { jQuery.cssHooks[ name ] = { get: function( elem, computed, extra ) { if ( computed ) { - // certain elements can have dimension info if we invisibly show them - // however, it must have a current display style that would benefit from this + + // Certain elements can have dimension info if we invisibly show them + // but it must have a current display style that would benefit return rdisplayswap.test( jQuery.css( elem, "display" ) ) && elem.offsetWidth === 0 ? jQuery.swap( elem, cssShow, function() { return getWidthOrHeight( elem, name, extra ); @@ -367,8 +368,6 @@ jQuery.each([ "height", "width" ], function( i, name ) { jQuery.cssHooks.marginRight = addGetHookIf( support.reliableMarginRight, function( elem, computed ) { if ( computed ) { - // WebKit Bug 13343 - getComputedStyle returns wrong value for margin-right - // Work around by temporarily setting element display to inline-block return jQuery.swap( elem, { "display": "inline-block" }, curCSS, [ elem, "marginRight" ] ); } @@ -386,7 +385,7 @@ jQuery.each({ var i = 0, expanded = {}, - // assumes a single number if not a string + // Assumes a single number if not a string parts = typeof value === "string" ? value.split(" ") : [ value ]; for ( ; i < 4; i++ ) { diff --git a/src/css/addGetHookIf.js b/src/css/addGetHookIf.js index 81d694cb0..e12f3598d 100644 --- a/src/css/addGetHookIf.js +++ b/src/css/addGetHookIf.js @@ -5,15 +5,13 @@ function addGetHookIf( conditionFn, hookFn ) { return { get: function() { if ( conditionFn() ) { - // Hook not needed (or it's not possible to use it due to missing dependency), - // remove it. - // Since there are no other hooks for marginRight, remove the whole object. + // Hook not needed (or it's not possible to use it due + // to missing dependency), remove it. delete this.get; return; } // Hook needed; redefine it so that the support test is not executed again. - return (this.get = hookFn).apply( this, arguments ); } }; diff --git a/src/css/curCSS.js b/src/css/curCSS.js index abcc8cb7f..90e508cb8 100644 --- a/src/css/curCSS.js +++ b/src/css/curCSS.js @@ -13,7 +13,7 @@ function curCSS( elem, name, computed ) { computed = computed || getStyles( elem ); // Support: IE9 - // getPropertyValue is only needed for .css('filter') in IE9, see #12537 + // getPropertyValue is only needed for .css('filter') (#12537) if ( computed ) { ret = computed.getPropertyValue( name ) || computed[ name ]; } diff --git a/src/css/defaultDisplay.js b/src/css/defaultDisplay.js index 631b9ba8a..046ae91b9 100644 --- a/src/css/defaultDisplay.js +++ b/src/css/defaultDisplay.js @@ -19,7 +19,7 @@ function actualDisplay( name, doc ) { // getDefaultComputedStyle might be reliably used only on attached element display = window.getDefaultComputedStyle && ( style = window.getDefaultComputedStyle( elem[ 0 ] ) ) ? - // Use of this method is a temporary fix (more like optmization) until something better comes along, + // Use of this method is a temporary fix (more like optimization) until something better comes along, // since it was removed from specification and supported only in FF style.display : jQuery.css( elem[ 0 ], "display" ); diff --git a/src/css/support.js b/src/css/support.js index 4a4d75c44..2cb6fe81d 100644 --- a/src/css/support.js +++ b/src/css/support.js @@ -13,6 +13,8 @@ define([ return; } + // Support: IE9-11+ + // Style of cloned element affects source element cloned (#8908) div.style.backgroundClip = "content-box"; div.cloneNode( true ).style.backgroundClip = ""; support.clearCloneStyle = div.style.backgroundClip === "content-box"; @@ -45,6 +47,7 @@ define([ if ( window.getComputedStyle ) { jQuery.extend( support, { pixelPosition: function() { + // This test is executed only once but we still do memoizing // since we can use the boxSizingReliable pre-computing. // No need to check if the test was already performed, though. @@ -58,6 +61,7 @@ define([ return boxSizingReliableVal; }, reliableMarginRight: function() { + // Support: Android 2.3 // Check if div with explicit width and no margin-right incorrectly // gets computed margin-right based on width of container. (#3333) diff --git a/src/data.js b/src/data.js index e3f3578fe..f9af9ae67 100644 --- a/src/data.js +++ b/src/data.js @@ -6,17 +6,16 @@ define([ "./data/var/data_user" ], function( jQuery, rnotwhite, access, data_priv, data_user ) { -/* - Implementation Summary - - 1. Enforce API surface and semantic compatibility with 1.9.x branch - 2. Improve the module's maintainability by reducing the storage - paths to a single mechanism. - 3. Use the same single mechanism to support "private" and "user" data. - 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) - 5. Avoid exposing implementation details on user objects (eg. expando properties) - 6. Provide a clear path for implementation upgrade to WeakMap in 2014 -*/ +// Implementation Summary +// +// 1. Enforce API surface and semantic compatibility with 1.9.x branch +// 2. Improve the module's maintainability by reducing the storage +// paths to a single mechanism. +// 3. Use the same single mechanism to support "private" and "user" data. +// 4. _Never_ expose "private" data to user code (TODO: Drop _data, _removeData) +// 5. Avoid exposing implementation details on user objects (eg. expando properties) +// 6. Provide a clear path for implementation upgrade to WeakMap in 2014 + var rbrace = /^(?:\{[\w\W]*\}|\[[\w\W]*\])$/, rmultiDash = /([A-Z])/g; diff --git a/src/data/Data.js b/src/data/Data.js index d34606bf2..423bef55b 100644 --- a/src/data/Data.js +++ b/src/data/Data.js @@ -5,7 +5,7 @@ define([ ], function( jQuery, rnotwhite ) { function Data() { - // Support: Android < 4, + // Support: Android<4, // Old WebKit does not have Object.preventExtensions/freeze method, // return new empty object instead with no [[set]] accessor Object.defineProperty( this.cache = {}, 0, { @@ -42,7 +42,7 @@ Data.prototype = { descriptor[ this.expando ] = { value: unlock }; Object.defineProperties( owner, descriptor ); - // Support: Android < 4 + // Support: Android<4 // Fallback to a less secure definition } catch ( e ) { descriptor[ this.expando ] = unlock; diff --git a/src/deferred.js b/src/deferred.js index 7fcc214ac..98f9c313f 100644 --- a/src/deferred.js +++ b/src/deferred.js @@ -119,7 +119,7 @@ jQuery.extend({ progressValues, progressContexts, resolveContexts; - // add listeners to Deferred subordinates; treat others as resolved + // Add listeners to Deferred subordinates; treat others as resolved if ( length > 1 ) { progressValues = new Array( length ); progressContexts = new Array( length ); @@ -136,7 +136,7 @@ jQuery.extend({ } } - // if we're not waiting on anything, resolve the master + // If we're not waiting on anything, resolve the master if ( !remaining ) { deferred.resolveWith( resolveContexts, resolveValues ); } diff --git a/src/dimensions.js b/src/dimensions.js index 9cb0e99f0..e6cb04c02 100644 --- a/src/dimensions.js +++ b/src/dimensions.js @@ -7,7 +7,7 @@ define([ // Create innerHeight, innerWidth, height, width, outerHeight and outerWidth methods jQuery.each( { Height: "height", Width: "width" }, function( name, type ) { jQuery.each( { padding: "inner" + name, content: type, "": "outer" + name }, function( defaultExtra, funcName ) { - // margin is only for outerHeight, outerWidth + // Margin is only for outerHeight, outerWidth jQuery.fn[ funcName ] = function( margin, value ) { var chainable = arguments.length && ( defaultExtra || typeof margin !== "boolean" ), extra = defaultExtra || ( margin === true || value === true ? "margin" : "border" ); diff --git a/src/effects.js b/src/effects.js index 5fafc528c..90226bd49 100644 --- a/src/effects.js +++ b/src/effects.js @@ -44,16 +44,16 @@ var start = +target || 1; do { - // If previous iteration zeroed out, double until we get *something* - // Use a string for doubling factor so we don't accidentally see scale as unchanged below + // If previous iteration zeroed out, double until we get *something*. + // Use string for doubling so we don't accidentally see scale as unchanged below scale = scale || ".5"; // Adjust and apply start = start / scale; jQuery.style( tween.elem, prop, start + unit ); - // Update scale, tolerating zero or NaN from tween.cur() - // And breaking the loop if scale is unchanged or perfect, or if we've just had enough + // Update scale, tolerating zero or NaN from tween.cur(), + // break the loop if scale is unchanged or perfect, or if we've just had enough } while ( scale !== (scale = tween.cur() / target) && scale !== 1 && --maxIterations ); } @@ -85,8 +85,8 @@ function genFx( type, includeWidth ) { i = 0, attrs = { height: type }; - // if we include width, step value is 1 to do all cssExpand values, - // if we don't include width, step value is 2 to skip over Left and Right + // If we include width, step value is 1 to do all cssExpand values, + // otherwise step value is 2 to skip over Left and Right includeWidth = includeWidth ? 1 : 0; for ( ; i < 4 ; i += 2 - includeWidth ) { which = cssExpand[ i ]; @@ -108,7 +108,7 @@ function createTween( value, prop, animation ) { for ( ; index < length; index++ ) { if ( (tween = collection[ index ].call( animation, prop, value )) ) { - // we're done with this property + // We're done with this property return tween; } } @@ -123,7 +123,7 @@ function defaultPrefilter( elem, props, opts ) { hidden = elem.nodeType && isHidden( elem ), dataShow = data_priv.get( elem, "fxshow" ); - // handle queue: false promises + // Handle queue: false promises if ( !opts.queue ) { hooks = jQuery._queueHooks( elem, "fx" ); if ( hooks.unqueued == null ) { @@ -138,8 +138,7 @@ function defaultPrefilter( elem, props, opts ) { hooks.unqueued++; anim.always(function() { - // doing this makes sure that the complete handler will be called - // before this completes + // Ensure the complete handler is called before this completes anim.always(function() { hooks.unqueued--; if ( !jQuery.queue( elem, "fx" ).length ) { @@ -149,7 +148,7 @@ function defaultPrefilter( elem, props, opts ) { }); } - // height/width overflow pass + // Height/width overflow pass if ( elem.nodeType === 1 && ( "height" in props || "width" in props ) ) { // Make sure that nothing sneaks out // Record all 3 overflow attributes because IE9-10 do not @@ -211,7 +210,7 @@ function defaultPrefilter( elem, props, opts ) { dataShow = data_priv.access( elem, "fxshow", {} ); } - // store state if its toggle - enables .stop().toggle() to "reverse" + // Store state if its toggle - enables .stop().toggle() to "reverse" if ( toggle ) { dataShow.hidden = !hidden; } @@ -271,8 +270,8 @@ function propFilter( props, specialEasing ) { value = hooks.expand( value ); delete props[ name ]; - // not quite $.extend, this wont overwrite keys already present. - // also - reusing 'index' from above because we have the correct "name" + // Not quite $.extend, this won't overwrite existing keys. + // Reusing 'index' because we have the correct "name" for ( index in value ) { if ( !( index in props ) ) { props[ index ] = value[ index ]; @@ -291,7 +290,7 @@ function Animation( elem, properties, options ) { index = 0, length = animationPrefilters.length, deferred = jQuery.Deferred().always( function() { - // don't match elem in the :animated selector + // Don't match elem in the :animated selector delete tick.elem; }), tick = function() { @@ -300,7 +299,8 @@ function Animation( elem, properties, options ) { } var currentTime = fxNow || createFxNow(), remaining = Math.max( 0, animation.startTime + animation.duration - currentTime ), - // archaic crash bug won't allow us to use 1 - ( 0.5 || 0 ) (#12497) + // Support: Android 2.3 + // Archaic crash bug won't allow us to use `1 - ( 0.5 || 0 )` (#12497) temp = remaining / animation.duration || 0, percent = 1 - temp, index = 0, @@ -336,7 +336,7 @@ function Animation( elem, properties, options ) { }, stop: function( gotoEnd ) { var index = 0, - // if we are going to the end, we want to run all the tweens + // If we are going to the end, we want to run all the tweens // otherwise we skip this part length = gotoEnd ? animation.tweens.length : 0; if ( stopped ) { @@ -347,8 +347,7 @@ function Animation( elem, properties, options ) { animation.tweens[ index ].run( 1 ); } - // resolve when we played the last frame - // otherwise, reject + // Resolve when we played the last frame; otherwise, reject if ( gotoEnd ) { deferred.resolveWith( elem, [ animation, gotoEnd ] ); } else { @@ -430,7 +429,7 @@ jQuery.speed = function( speed, easing, fn ) { opt.duration = jQuery.fx.off ? 0 : typeof opt.duration === "number" ? opt.duration : opt.duration in jQuery.fx.speeds ? jQuery.fx.speeds[ opt.duration ] : jQuery.fx.speeds._default; - // normalize opt.queue - true/undefined/null -> "fx" + // Normalize opt.queue - true/undefined/null -> "fx" if ( opt.queue == null || opt.queue === true ) { opt.queue = "fx"; } @@ -454,10 +453,10 @@ jQuery.speed = function( speed, easing, fn ) { jQuery.fn.extend({ fadeTo: function( speed, to, easing, callback ) { - // show any hidden elements after setting opacity to 0 + // Show any hidden elements after setting opacity to 0 return this.filter( isHidden ).css( "opacity", 0 ).show() - // animate to the value specified + // Animate to the value specified .end().animate({ opacity: to }, speed, easing, callback ); }, animate: function( prop, speed, easing, callback ) { @@ -520,9 +519,9 @@ jQuery.fn.extend({ } } - // start the next in the queue if the last step wasn't forced - // timers currently will call their complete callbacks, which will dequeue - // but only if they were gotoEnd + // Start the next in the queue if the last step wasn't forced. + // Timers currently will call their complete callbacks, which + // will dequeue but only if they were gotoEnd. if ( dequeue || !gotoEnd ) { jQuery.dequeue( this, type ); } @@ -540,17 +539,17 @@ jQuery.fn.extend({ timers = jQuery.timers, length = queue ? queue.length : 0; - // enable finishing flag on private data + // Enable finishing flag on private data data.finish = true; - // empty the queue first + // Empty the queue first jQuery.queue( this, type, [] ); if ( hooks && hooks.stop ) { hooks.stop.call( this, true ); } - // look for any active animations, and finish them + // Look for any active animations, and finish them for ( index = timers.length; index--; ) { if ( timers[ index ].elem === this && timers[ index ].queue === type ) { timers[ index ].anim.stop( true ); @@ -558,14 +557,14 @@ jQuery.fn.extend({ } } - // look for any animations in the old queue and finish them + // Look for any animations in the old queue and finish them for ( index = 0; index < length; index++ ) { if ( queue[ index ] && queue[ index ].finish ) { queue[ index ].finish.call( this ); } } - // turn off finishing flag + // Turn off finishing flag delete data.finish; }); } diff --git a/src/effects/Tween.js b/src/effects/Tween.js index d1e4dca8b..9acd8d0cc 100644 --- a/src/effects/Tween.js +++ b/src/effects/Tween.js @@ -64,17 +64,18 @@ Tween.propHooks = { return tween.elem[ tween.prop ]; } - // passing an empty string as a 3rd parameter to .css will automatically - // attempt a parseFloat and fallback to a string if the parse fails - // so, simple values such as "10px" are parsed to Float. - // complex values such as "rotate(1rad)" are returned as is. + // Passing an empty string as a 3rd parameter to .css will automatically + // attempt a parseFloat and fallback to a string if the parse fails. + // Simple values such as "10px" are parsed to Float; + // complex values such as "rotate(1rad)" are returned as-is. result = jQuery.css( tween.elem, tween.prop, "" ); // Empty strings, null, undefined and "auto" are converted to 0. return !result || result === "auto" ? 0 : result; }, set: function( tween ) { - // use step hook for back compat - use cssHook if its there - use .style if its - // available and use plain properties where available + // Use step hook for back compat. + // Use cssHook if its there. + // Use .style if available and use plain properties where available. if ( jQuery.fx.step[ tween.prop ] ) { jQuery.fx.step[ tween.prop ]( tween ); } else if ( tween.elem.style && ( tween.elem.style[ jQuery.cssProps[ tween.prop ] ] != null || jQuery.cssHooks[ tween.prop ] ) ) { @@ -88,7 +89,6 @@ Tween.propHooks = { // Support: IE9 // Panic based approach to setting things on disconnected nodes - Tween.propHooks.scrollTop = Tween.propHooks.scrollLeft = { set: function( tween ) { if ( tween.elem.nodeType && tween.elem.parentNode ) { diff --git a/src/event.js b/src/event.js index f38d70a40..8f04b89c1 100644 --- a/src/event.js +++ b/src/event.js @@ -379,8 +379,8 @@ jQuery.event = { j = 0; while ( (handleObj = matched.handlers[ j++ ]) && !event.isImmediatePropagationStopped() ) { - // Triggered event must either 1) have no namespace, or - // 2) have namespace(s) a subset or equal to those in the bound event (both can have no namespace). + // Triggered event must either 1) have no namespace, or 2) have namespace(s) + // a subset or equal to those in the bound event (both can have no namespace). if ( !event.namespace_re || event.namespace_re.test( handleObj.namespace ) ) { event.handleObj = handleObj; @@ -530,7 +530,7 @@ jQuery.event = { event.target = document; } - // Support: Safari 6.0+, Chrome < 28 + // Support: Safari 6.0+, Chrome<28 // Target should not be a text node (#504, #13143) if ( event.target.nodeType === 3 ) { event.target = event.target.parentNode; @@ -635,7 +635,7 @@ jQuery.Event = function( src, props ) { // by a handler lower down the tree; reflect the correct value. this.isDefaultPrevented = src.defaultPrevented || src.defaultPrevented === undefined && - // Support: Android < 4.0 + // Support: Android<4.0 src.returnValue === false ? returnTrue : returnFalse; @@ -725,8 +725,8 @@ jQuery.each({ }; }); -// Create "bubbling" focus and blur events // Support: Firefox, Chrome, Safari +// Create "bubbling" focus and blur events if ( !support.focusinBubbles ) { jQuery.each({ focus: "focusin", blur: "focusout" }, function( orig, fix ) { diff --git a/src/exports/global.js b/src/exports/global.js index 8eee5bb7f..6513287c6 100644 --- a/src/exports/global.js +++ b/src/exports/global.js @@ -22,8 +22,8 @@ jQuery.noConflict = function( deep ) { return jQuery; }; -// Expose jQuery and $ identifiers, even in -// AMD (#7102#comment:10, https://github.com/jquery/jquery/pull/557) +// Expose jQuery and $ identifiers, even in AMD +// (#7102#comment:10, https://github.com/jquery/jquery/pull/557) // and CommonJS for browser emulators (#13566) if ( typeof noGlobal === strundefined ) { window.jQuery = window.$ = jQuery; diff --git a/src/intro.js b/src/intro.js index f7dd78d3f..d7d436807 100644 --- a/src/intro.js +++ b/src/intro.js @@ -15,13 +15,13 @@ (function( global, factory ) { if ( typeof module === "object" && typeof module.exports === "object" ) { - // For CommonJS and CommonJS-like environments where a proper window is present, - // execute the factory and get jQuery - // For environments that do not inherently posses a window with a document - // (such as Node.js), expose a jQuery-making factory as module.exports - // This accentuates the need for the creation of a real window + // For CommonJS and CommonJS-like environments where a proper `window` + // is present, execute the factory and get jQuery. + // For environments that do not have a `window` with a `document` + // (such as Node.js), expose a factory as module.exports. + // This accentuates the need for the creation of a real `window`. // e.g. var jQuery = require("jquery")(window); - // See ticket #14549 for more info + // See ticket #14549 for more info. module.exports = global.document ? factory( global, true ) : function( w ) { @@ -37,8 +37,8 @@ // Pass this if window is not defined yet }(typeof window !== "undefined" ? window : this, function( window, noGlobal ) { -// Can't do this because several apps including ASP.NET trace +// Support: Firefox 18+ +// Can't be in strict mode, several libs including ASP.NET trace // the stack via arguments.caller.callee and Firefox dies if // you try to trace through "use strict" call chains. (#13335) -// Support: Firefox 18+ //"use strict"; diff --git a/src/manipulation.js b/src/manipulation.js index 31d0c4edc..c62796264 100644 --- a/src/manipulation.js +++ b/src/manipulation.js @@ -29,7 +29,7 @@ var // We have to close these tags to support XHTML (#13200) wrapMap = { - // Support: IE 9 + // Support: IE9 option: [ 1, "" ], thead: [ 1, "", "
" ], @@ -40,7 +40,7 @@ var _default: [ 0, "", "" ] }; -// Support: IE 9 +// Support: IE9 wrapMap.optgroup = wrapMap.option; wrapMap.tbody = wrapMap.tfoot = wrapMap.colgroup = wrapMap.caption = wrapMap.thead; @@ -130,7 +130,7 @@ function getAll( context, tag ) { ret; } -// Support: IE >= 9 +// Fix IE bugs, see support tests function fixInput( src, dest ) { var nodeName = dest.nodeName.toLowerCase(); @@ -150,8 +150,7 @@ jQuery.extend({ clone = elem.cloneNode( true ), inPage = jQuery.contains( elem.ownerDocument, elem ); - // Support: IE >= 9 - // Fix Cloning issues + // Fix IE cloning issues if ( !support.noCloneChecked && ( elem.nodeType === 1 || elem.nodeType === 11 ) && !jQuery.isXMLDoc( elem ) ) { @@ -202,8 +201,8 @@ jQuery.extend({ // Add nodes directly if ( jQuery.type( elem ) === "object" ) { - // Support: QtWebKit - // jQuery.merge because push.apply(_, arraylike) throws + // Support: QtWebKit, PhantomJS + // push.apply(_, arraylike) throws on ancient WebKit jQuery.merge( nodes, elem.nodeType ? [ elem ] : elem ); // Convert non-html into a text node @@ -225,15 +224,14 @@ jQuery.extend({ tmp = tmp.lastChild; } - // Support: QtWebKit - // jQuery.merge because push.apply(_, arraylike) throws + // Support: QtWebKit, PhantomJS + // push.apply(_, arraylike) throws on ancient WebKit jQuery.merge( nodes, tmp.childNodes ); // Remember the top-level container tmp = fragment.firstChild; - // Fixes #12346 - // Support: Webkit, IE + // Ensure the created nodes are orphaned (#12392) tmp.textContent = ""; } } diff --git a/src/manipulation/support.js b/src/manipulation/support.js index fb1e85567..822a014f5 100644 --- a/src/manipulation/support.js +++ b/src/manipulation/support.js @@ -7,21 +7,22 @@ define([ div = fragment.appendChild( document.createElement( "div" ) ), input = document.createElement( "input" ); - // #11217 - WebKit loses check when the name is after the checked attribute + // Support: Safari<=5.1 + // Check state lost if the name is set (#11217) // Support: Windows Web Apps (WWA) - // `name` and `type` need .setAttribute for WWA + // `name` and `type` must use .setAttribute for WWA (#14901) input.setAttribute( "type", "radio" ); input.setAttribute( "checked", "checked" ); input.setAttribute( "name", "t" ); div.appendChild( input ); - // Support: Safari 5.1, iOS 5.1, Android 4.x, Android 2.3 - // old WebKit doesn't clone checked state correctly in fragments + // Support: Safari<=5.1, Android<4.2 + // Older WebKit doesn't clone checked state correctly in fragments support.checkClone = div.cloneNode( true ).cloneNode( true ).lastChild.checked; + // Support: IE<=11+ // Make sure textarea (and checkbox) defaultValue is properly cloned - // Support: IE9-IE11+ div.innerHTML = ""; support.noCloneChecked = !!div.cloneNode( true ).lastChild.defaultValue; })(); diff --git a/src/offset.js b/src/offset.js index dc7bb9557..4c34fd0ef 100644 --- a/src/offset.js +++ b/src/offset.js @@ -39,7 +39,8 @@ jQuery.offset = { calculatePosition = ( position === "absolute" || position === "fixed" ) && ( curCSSTop + curCSSLeft ).indexOf("auto") > -1; - // Need to be able to calculate position if either top or left is auto and position is either absolute or fixed + // Need to be able to calculate position if either + // top or left is auto and position is either absolute or fixed if ( calculatePosition ) { curPosition = curElem.position(); curTop = curPosition.top; @@ -96,8 +97,8 @@ jQuery.fn.extend({ return box; } + // Support: BlackBerry 5, iOS 3 (original iPhone) // If we don't have gBCR, just use 0,0 rather than error - // BlackBerry 5, iOS 3 (original iPhone) if ( typeof elem.getBoundingClientRect !== strundefined ) { box = elem.getBoundingClientRect(); } @@ -119,7 +120,7 @@ jQuery.fn.extend({ // Fixed elements are offset from window (parentOffset = {top:0, left: 0}, because it is its only offset parent if ( jQuery.css( elem, "position" ) === "fixed" ) { - // We assume that getBoundingClientRect is available when computed position is fixed + // Assume getBoundingClientRect is there when computed position is fixed offset = elem.getBoundingClientRect(); } else { @@ -182,16 +183,18 @@ jQuery.each( { scrollLeft: "pageXOffset", scrollTop: "pageYOffset" }, function( }; }); +// Support: Safari<7+, Chrome<37+ // Add the top/left cssHooks using jQuery.fn.position // Webkit bug: https://bugs.webkit.org/show_bug.cgi?id=29084 -// getComputedStyle returns percent when specified for top/left/bottom/right -// rather than make the css module depend on the offset module, we just check for it here +// Blink bug: https://code.google.com/p/chromium/issues/detail?id=229280 +// getComputedStyle returns percent when specified for top/left/bottom/right; +// rather than make the css module depend on the offset module, just check for it here jQuery.each( [ "top", "left" ], function( i, prop ) { jQuery.cssHooks[ prop ] = addGetHookIf( support.pixelPosition, function( elem, computed ) { if ( computed ) { computed = curCSS( elem, prop ); - // if curCSS returns percentage, fallback to offset + // If curCSS returns percentage, fallback to offset return rnumnonpx.test( computed ) ? jQuery( elem ).position()[ prop ] + "px" : computed; diff --git a/src/queue.js b/src/queue.js index fbfaf9ca5..199c56d36 100644 --- a/src/queue.js +++ b/src/queue.js @@ -50,7 +50,7 @@ jQuery.extend({ queue.unshift( "inprogress" ); } - // clear up the last queue stop function + // Clear up the last queue stop function delete hooks.stop; fn.call( elem, next, hooks ); } @@ -60,7 +60,7 @@ jQuery.extend({ } }, - // not intended for public consumption - generates a queueHooks object, or returns the current one + // Not public - generate a queueHooks object, or return the current one _queueHooks: function( elem, type ) { var key = type + "queueHooks"; return data_priv.get( elem, key ) || data_priv.access( elem, key, { @@ -90,7 +90,7 @@ jQuery.fn.extend({ this.each(function() { var queue = jQuery.queue( this, type, data ); - // ensure a hooks for this queue + // Ensure a hooks for this queue jQuery._queueHooks( this, type ); if ( type === "fx" && queue[0] !== "inprogress" ) { diff --git a/src/traversing.js b/src/traversing.js index 943d16cb6..d9ff0aeac 100644 --- a/src/traversing.js +++ b/src/traversing.js @@ -8,7 +8,7 @@ define([ ], function( jQuery, indexOf, rneedsContext ) { var rparentsprev = /^(?:parents|prev(?:Until|All))/, - // methods guaranteed to produce a unique set when starting from a unique set + // Methods guaranteed to produce a unique set when starting from a unique set guaranteedUnique = { children: true, contents: true, @@ -88,8 +88,7 @@ jQuery.fn.extend({ return this.pushStack( matched.length > 1 ? jQuery.unique( matched ) : matched ); }, - // Determine the position of an element within - // the matched set of elements + // Determine the position of an element within the set index: function( elem ) { // No argument, return index in parent @@ -97,7 +96,7 @@ jQuery.fn.extend({ return ( this[ 0 ] && this[ 0 ].parentNode ) ? this.first().prevAll().length : -1; } - // index in selector + // Index in selector if ( typeof elem === "string" ) { return indexOf.call( jQuery( elem ), this[ 0 ] ); } -- 2.39.5