Docs: Improve JSDoc for `js/wp-emoji-loader.js`.

Props nicollle, dfangstrom, Igorsch.
Fixes #43870.


git-svn-id: https://develop.svn.wordpress.org/trunk@43143 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/js/wp-emoji-loader.js

@@ -1,19 +1,21 @@
 ( function( window, document, settings ) {
 	var src, ready, ii, tests;
 
-	/*
+	// Create a canvas element for testing native browser support of emoji.
-	 * Create a canvas element for testing native browser support
-	 * of emoji.
-	 */
 	var canvas = document.createElement( 'canvas' );
 	var context = canvas.getContext && canvas.getContext( '2d' );
 
 	/**
-	 * Check if two sets of Emoji characters render the same.
+	 * Checks if two sets of Emoji characters render the same visually.
 	 *
-	 * @param set1 array Set of Emoji characters.
+	 * @since 4.9.0
-	 * @param set2 array Set of Emoji characters.
+	 *
-	 * @returns {boolean} True if the two sets render the same.
+	 * @private
+	 *
+	 * @param {number[]} set1 Set of Emoji character codes.
+	 * @param {number[]} set2 Set of Emoji character codes.
+	 *
+	 * @return {boolean} True if the two sets render the same.
 	 */
 	function emojiSetsRenderIdentically( set1, set2 ) {
 		var stringFromCharCode = String.fromCharCode;
@@ -32,13 +34,18 @@
 	}
 
 	/**
-	 * Detect if the browser supports rendering emoji or flag emoji. Flag emoji are a single glyph
+	 * Detects if the browser supports rendering emoji or flag emoji.
-	 * made of two characters, so some browsers (notably, Firefox OS X) don't support them.
+	 *
+	 * Flag emoji are a single glyph made of two characters, so some browsers
+	 * (notably, Firefox OS X) don't support them.
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param type {String} Whether to test for support of "flag" or "emoji".
+	 * @private
-	 * @return {Boolean} True if the browser can render emoji, false if it cannot.
+	 *
+	 * @param {string} type Whether to test for support of "flag" or "emoji".
+	 *
+	 * @return {boolean} True if the browser can render emoji, false if it cannot.
 	 */
 	function browserSupportsEmoji( type ) {
 		var isIdentical;
@@ -104,6 +111,16 @@
 		return false;
 	}
 
+	/**
+	 * Adds a script to the head of the document.
+	 *
+	 * @ignore
+	 *
+	 * @since 4.2.0
+	 *
+	 * @param {Object} src The url where the script is located.
+	 * @return {void}
+	 */
 	function addScript( src ) {
 		var script = document.createElement( 'script' );
 
@@ -119,6 +136,10 @@
 		everythingExceptFlag: true
 	};
 
+	/*
+	 * Tests the browser support for flag emojis and other emojis, and adjusts the
+	 * support settings accordingly.
+	 */
 	for( ii = 0; ii < tests.length; ii++ ) {
 		settings.supports[ tests[ ii ] ] = browserSupportsEmoji( tests[ ii ] );
 
@@ -131,16 +152,21 @@
 
 	settings.supports.everythingExceptFlag = settings.supports.everythingExceptFlag && ! settings.supports.flag;
 
+	// Sets DOMReady to false and assigns a ready function to settings.
 	settings.DOMReady = false;
 	settings.readyCallback = function() {
 		settings.DOMReady = true;
 	};
 
+	// When the browser can not render everything we need to load a polyfill.
 	if ( ! settings.supports.everything ) {
 		ready = function() {
 			settings.readyCallback();
 		};
 
+		/*
+		 * Cross-browser version of adding a dom ready event.
+		 */
 		if ( document.addEventListener ) {
 			document.addEventListener( 'DOMContentLoaded', ready, false );
 			window.addEventListener( 'load', ready, false );