whitespace and comment updates only

loadCSS.js

@@ -1,27 +1,25 @@
 /*!
 loadCSS: load a CSS file asynchronously.
-[c]2014 @scottjehl, Filament Group, Inc.
+[c]2015 @scottjehl, Filament Group, Inc.
 Licensed MIT
 */
 
 /* exported loadCSS */
 function loadCSS( href, before, media ){
 	"use strict";
 	// Arguments explained:
-	// `href` is the URL for your CSS file.
-	// `before` optionally defines the element we'll use as a reference for injecting our <link> before
-	// By default, loadCSS attempts to inject the link after the last stylesheet or script in the DOM
-	// However, you might desire a more specific location in your document.
-	// If so, pass a different reference element to the `before` argument and it'll insert before that instead
-	// note: `insertBefore` is used instead of `appendChild`, for safety re: http://www.paulirish.com/2011/surefire-dom-element-insertion/
+	// `href` [REQUIRED] is the URL for your CSS file.
+	// `before` [OPTIONAL] is the element the script should use as a reference for injecting our stylesheet <link> before
+		// By default, loadCSS attempts to inject the link after the last stylesheet or script in the DOM. However, you might desire a more specific location in your document.
+	// `media` [OPTIONAL] is the media type or query of the stylesheet. By default it will be 'all'
 	var ss = window.document.createElement( "link" );
 	var ref;
 	if( before ){
 		ref = before;
 	}
 	else if( window.document.querySelectorAll ){
 		var refs = window.document.querySelectorAll(  "style,link[rel=stylesheet],script" );
-		// no need to check length - this script has a parent element, at least
+		// No need to check length. This script has a parent element, at least
 		ref = refs[ refs.length - 1];
 	}
 	else {
@@ -31,14 +29,14 @@ function loadCSS( href, before, media ){
 	var sheets = window.document.styleSheets;
 	ss.rel = "stylesheet";
 	ss.href = href;
-	// temporarily, set media to something non-matching to ensure it'll fetch without blocking render
+	// temporarily set media to something inapplicable to ensure it'll fetch without blocking render
 	ss.media = "only x";
 
-	// inject link
-	// Note: the ternary preserves the existing behavior of "before" argument, but we could choose to change the argument to "after" in a later release and standardize on ref.nextSibling for all refs
+	// Inject link
+		// Note: the ternary preserves the existing behavior of "before" argument, but we could choose to change the argument to "after" in a later release and standardize on ref.nextSibling for all refs
+		// Note: `insertBefore` is used instead of `appendChild`, for safety re: http://www.paulirish.com/2011/surefire-dom-element-insertion/
 	ref.parentNode.insertBefore( ss, ( before ? ref : ref.nextSibling ) );
-	// This function sets the link's media back to `all` so that the stylesheet applies once it loads
-	// It is designed to poll until window.document.styleSheets includes the new sheet.
+	// A method (exposed on return object for external use) that mimics onload by polling until window.document.styleSheets until it includes the new sheet.
 	ss.onloadcssdefined = function( cb ){
 		var defined;
 		for( var i = 0; i < sheets.length; i++ ){
@@ -54,6 +52,8 @@ function loadCSS( href, before, media ){
 			});
 		}
 	};
+
+	// once loaded, set link's media back to `all` so that the stylesheet applies once it loads
 	ss.onloadcssdefined(function() {
 		ss.media = media || "all";
 	});