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
This commit is contained in:
Anton Timmermans 2018-05-03 15:08:39 +00:00
parent 3aa3b05cc2
commit 3efc98cae6
1 changed files with 38 additions and 12 deletions

View File

@ -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.
* @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 ) {
var stringFromCharCode = String.fromCharCode;
@ -32,13 +34,18 @@
}
/**
* 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 ) {
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 );