Changeset 43143

Timestamp:

05/03/2018 03:08:39 PM (8 years ago)

Author:

atimmer

Message:

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

Props nicollle, dfangstrom, Igorsch.
Fixes #43870.

File:

• trunk/src/wp-includes/js/wp-emoji-loader.js (modified) (7 diffs)

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

@@ -2 +2 @@
         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.
-         * @param set2 array Set of Emoji characters.
-         * @returns {boolean} True if the two sets render the same.
+         * @since 4.9.0
+         *
+         * @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 ) {
@@ -33 +35 @@
 
         /**
-         * Detect if the browser supports rendering emoji or flag emoji. Flag emoji are a single glyph
-         * made of two characters, so some browsers (notably, Firefox OS X) don't support them.
+         * Detects if the browser supports rendering emoji or flag emoji.
+         *
+         * 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".
-         * @return {Boolean} True if the browser can render emoji, false if it cannot.
+         * @private
+         *
+         * @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 ) {
@@ -105 +112 @@
         }
 
+        /**
+         * 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' );
@@ -120 +137 @@
         };
 
+        /*
+         * 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 ] );
@@ -132 +153 @@
         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() {
@@ -137 +159 @@
         };
 
+        // When the browser can not render everything we need to load a polyfill.
         if ( ! settings.supports.everything ) {
                 ready = function() {
@@ -142 +165 @@
                 };
 
+                /*
+                 * Cross-browser version of adding a dom ready event.
+                 */
                 if ( document.addEventListener ) {
                         document.addEventListener( 'DOMContentLoaded', ready, false );