Docs: Improve JSDoc for `emoji.js`.

Props lisannekluitmans, hansjovisyoast, igorsch, nicollle.
Fixes #44367.

Built from https://develop.svn.wordpress.org/trunk@43360


git-svn-id: http://core.svn.wordpress.org/trunk@43188 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/js/wp-emoji.js

@@ -1,8 +1,24 @@
 /**
+ * wp-emoji.js is used to replace emoji with images in browsers when the browser
+ * doesn't support emoji natively.
+ *
  * @output wp-includes/js/wp-emoji.js
  */
 
 ( function( window, settings ) {
+	/**
+	 * Replaces emoji with images when browsers don't support emoji.
+	 *
+	 * @since      4.2.0
+	 * @access     private
+	 *
+	 * @class
+	 *
+	 * @see  Twitter Emoji library
+	 * @link https://github.com/twitter/twemoji
+	 *
+	 * @return {Object} The wpEmoji parse and test functions.
+	 */
 	function wpEmoji() {
 		var MutationObserver = window.MutationObserver || window.WebKitMutationObserver || window.MozMutationObserver,
 
@@ -19,13 +35,15 @@
 		 * Detect if the browser supports SVG.
 		 *
 		 * @since 4.6.0
+		 * @private
 		 *
-		 * @return {Boolean} True if the browser supports svg, false if not.
+		 * @see Modernizr
+		 * @link https://github.com/Modernizr/Modernizr/blob/master/feature-detects/svg/asimg.js
+		 *
+		 * @return {boolean} True if the browser supports svg, false if not.
 		 */
 		function browserSupportsSvgAsImage() {
 			if ( !! document.implementation.hasFeature ) {
-				// Source: Modernizr
-				// https://github.com/Modernizr/Modernizr/blob/master/feature-detects/svg/asimg.js
 				return document.implementation.hasFeature( 'http://www.w3.org/TR/SVG11/feature#Image', '1.1' );
 			}
 
@@ -35,15 +53,21 @@
 		}
 
 		/**
-		 * Runs when the document load event is fired, so we can do our first parse of the page.
+		 * Runs when the document load event is fired, so we can do our first parse of
+		 * the page.
+		 *
+		 * Listens to all the DOM mutations and checks for added nodes that contain
+		 * emoji characters and replaces those with twitter emoji images.
 		 *
 		 * @since 4.2.0
+		 * @private
 		 */
 		function load() {
 			if ( loaded ) {
 				return;
 			}
 
+			// Ensure twemoji is available on the global window before proceeding.
 			if ( typeof window.twemoji === 'undefined' ) {
 				// Break if waiting for longer than 30 sec.
 				if ( count > 600 ) {
@@ -61,6 +85,8 @@
 			twemoji = window.twemoji;
 			loaded = true;
 
+			// Initialize the mutation observer, which checks all added nodes for
+			// replaceable emoji characters.
 			if ( MutationObserver ) {
 				new MutationObserver( function( mutationRecords ) {
 					var i = mutationRecords.length,
@@ -71,6 +97,16 @@
 						removedNodes = mutationRecords[ i ].removedNodes;
 						ii = addedNodes.length;
 
+						/*
+						 * Checks if an image has been replaced by a text element
+						 * with the same text as the alternate description of the replaced image.
+						 * (presumably because the image could not be loaded).
+						 * If it is, do absolutely nothing.
+						 *
+						 * Node type 3 is a TEXT_NODE.
+						 *
+						 * @link https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType
+						 */
 						if (
 							ii === 1 && removedNodes.length === 1 &&
 							addedNodes[0].nodeType === 3 &&
@@ -81,9 +117,11 @@
 							return;
 						}
 
+						// Loop through all the added nodes.
 						while ( ii-- ) {
 							node = addedNodes[ ii ];
 
+							// Node type 3 is a TEXT_NODE.
 							if ( node.nodeType === 3 ) {
 								if ( ! node.parentNode ) {
 									continue;
@@ -95,6 +133,8 @@
 									 * It unnecessarily splits text nodes when it encounters a HTML
 									 * template interpolation symbol ( "{{", for example ). So, we
 									 * join the text nodes back together as a work-around.
+									 *
+									 * Node type 3 is a TEXT_NODE.
 									 */
 									while( node.nextSibling && 3 === node.nextSibling.nodeType ) {
 										node.nodeValue = node.nodeValue + node.nextSibling.nodeValue;
@@ -105,6 +145,11 @@
 								node = node.parentNode;
 							}
 
+							/*
+							 * If the class name of a non-element node contains 'wp-exclude-emoji' ignore it.
+							 *
+							 * Node type 1 is an ELEMENT_NODE.
+							 */
 							if ( ! node || node.nodeType !== 1 ||
 								( node.className && typeof node.className === 'string' && node.className.indexOf( 'wp-exclude-emoji' ) !== -1 ) ) {
 
@@ -126,13 +171,15 @@
 		}
 
 		/**
-		 * Test if a text string contains emoji characters.
+		 * Tests if a text string contains emoji characters.
 		 *
 		 * @since 4.3.0
 		 *
-		 * @param {String} text The string to test
+		 * @memberOf wp.emoji
 		 *
-		 * @return {Boolean} Whether the string contains emoji characters.
+		 * @param {string} text The string to test.
+		 *
+		 * @return {boolean} Whether the string contains emoji characters.
 		 */
 		function test( text ) {
 			// Single char. U+20E3 to detect keycaps. U+00A9 "copyright sign" and U+00AE "registered sign" not included.
@@ -148,22 +195,36 @@
 		}
 
 		/**
-		 * Given an element or string, parse any emoji characters into Twemoji images.
+		 * Parses any emoji characters into Twemoji images.
+		 *
+		 * - When passed an element the emoji characters are replaced inline.
+		 * - When passed a string the emoji characters are replaced and the result is
+		 *   returned.
 		 *
 		 * @since 4.2.0
 		 *
-		 * @param {HTMLElement|String} object The element or string to parse.
+		 * @memberOf wp.emoji
-		 * @param {Object} args Additional options for Twemoji.
+		 *
+		 * @param {HTMLElement|string} object The element or string to parse.
+		 * @param {Object}             args   Additional options for Twemoji.
+		 *
+		 * @return {HTMLElement|string} A string where all emoji are now image tags of
+		 *                              emoji. Or the element that was passed as the first argument.
 		 */
 		function parse( object, args ) {
 			var params;
 
+			/*
+			 * If the browser has full support, twemoji is not loaded or our
+			 * object is not what was expected, we do not parse anything.
+			 */
 			if ( settings.supports.everything || ! twemoji || ! object ||
 				( 'string' !== typeof object && ( ! object.childNodes || ! object.childNodes.length ) ) ) {
 
 				return object;
 			}
 
+			// Compose the params for the twitter emoji library.
 			args = args || {};
 			params = {
 				base: browserSupportsSvgAsImage() ? settings.svgUrl : settings.baseUrl,
@@ -227,6 +288,10 @@
 	}
 
 	window.wp = window.wp || {};
+
+	/**
+	 * @namespace wp.emoji
+	 */
 	window.wp.emoji = new wpEmoji();
 
 } )( window, window._wpemojiSettings );

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.0-alpha-43359';
+$wp_version = '5.0-alpha-43360';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.