From 7bbdceb336e7eaa0007f81f3eb0da1ac1fe46509 Mon Sep 17 00:00:00 2001
From: Drew Jaynes <drewapicture@git.wordpress.org>
Date: Mon, 16 Mar 2015 01:42:26 +0000
Subject: [PATCH] Clean up some inline documentation for emoji functionality,
 including a missing `@since` for `mail_emoji()`, and a changelog entry for
 `wp_insert_post()`.

See #31242.


git-svn-id: https://develop.svn.wordpress.org/trunk@31789 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/formatting.php    | 26 +++++++++++++++++---------
 src/wp-includes/post.php          |  1 +
 src/wp-includes/script-loader.php |  3 ++-
 3 files changed, 20 insertions(+), 10 deletions(-)

diff --git a/src/wp-includes/formatting.php b/src/wp-includes/formatting.php
index 6c23bbb19a..266397dfc6 100644
--- a/src/wp-includes/formatting.php
+++ b/src/wp-includes/formatting.php
@@ -4057,6 +4057,7 @@ img.emoji {
 
 /**
  * Convert any 4 byte emoji in a string to their equivalent HTML entity.
+ *
  * Currently, only Unicode 7 emoji are supported. Unicode 8 emoji will be added
  * when the spec in finalised, along with the new skin-tone modifiers.
  *
@@ -4103,7 +4104,7 @@ function wp_encode_emoji( $content ) {
 }
 
 /**
- * Convert emoji to a static <img> link.
+ * Convert emoji to a static img element.
  *
  * @since 4.2.0
  *
@@ -4119,27 +4120,33 @@ function wp_staticize_emoji( $text ) {
 
 	/** This filter is documented in wp-includes/script-loader.php */
 	$cdn_url = apply_filters( 'emoji_url', '//s0.wp.com/wp-content/mu-plugins/emoji/twemoji/72x72/' );
+
 	/** This filter is documented in wp-includes/script-loader.php */
 	$ext = apply_filters( 'emoji_ext', '.png' );
 
 	$output = '';
-	// HTML loop taken from smiley function, which was taking from texturize function. It'll never be consolidated.
-	$textarr = preg_split( '/(<.*>)/U', $text, -1, PREG_SPLIT_DELIM_CAPTURE ); // capture the tags as well as in between
-	$stop = count( $textarr );// loop stuff
+	/*
+	 * HTML loop taken from smiley function, which was taking from texturize function.
+	 * It'll never be consolidated.
+	 *
+	 * First, capture the tags as well as in between.
+	 */
+	$textarr = preg_split( '/(<.*>)/U', $text, -1, PREG_SPLIT_DELIM_CAPTURE );
+	$stop = count( $textarr );
 
-	// Ignore proessing of specific tags
+	// Ignore processing of specific tags.
 	$tags_to_ignore = 'code|pre|style|script|textarea';
 	$ignore_block_element = '';
 
 	for ( $i = 0; $i < $stop; $i++ ) {
 		$content = $textarr[$i];
 
-		// If we're in an ignore block, wait until we find its closing tag
+		// If we're in an ignore block, wait until we find its closing tag.
 		if ( '' == $ignore_block_element && preg_match( '/^<(' . $tags_to_ignore . ')>/', $content, $matches ) )  {
 			$ignore_block_element = $matches[1];
 		}
 
-		// If it's not a tag and not in ignore block
+		// If it's not a tag and not in ignore block.
 		if ( '' ==  $ignore_block_element && strlen( $content ) > 0 && '<' != $content[0] ) {
 			$matches = array();
 			if ( preg_match_all( '/(&#x1f1(e[6-9a-f]|f[0-9a-f]);){2}/', $content, $matches ) ) {
@@ -4171,7 +4178,7 @@ function wp_staticize_emoji( $text ) {
 			}
 		}
 
-		// did we exit ignore block
+		// Did we exit ignore block.
 		if ( '' != $ignore_block_element && '</' . $ignore_block_element . '>' == $content )  {
 			$ignore_block_element = '';
 		}
@@ -4185,8 +4192,9 @@ function wp_staticize_emoji( $text ) {
 /**
  * Convert emoji in emails into static images.
  *
- * @param array $mail The email data array.
+ * @since 4.2.0
  *
+ * @param array $mail The email data array.
  * @return array The email data array, with emoji in the message staticized.
  */
 function mail_emoji( $mail ) {
diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php
index 4bd4f8e0cf..3c174d3544 100644
--- a/src/wp-includes/post.php
+++ b/src/wp-includes/post.php
@@ -3048,6 +3048,7 @@ function wp_get_recent_posts( $args = array(), $output = ARRAY_A ) {
  * setting the value for 'comment_status' key.
  *
  * @since 1.0.0
+ * @since 4.2.0 Support was added for encoding emoji in the post title, content, and excerpt.
  *
  * @see sanitize_post()
  * @global wpdb $wpdb WordPress database abstraction object.
diff --git a/src/wp-includes/script-loader.php b/src/wp-includes/script-loader.php
index f426b9dd0e..8120e3dbf9 100644
--- a/src/wp-includes/script-loader.php
+++ b/src/wp-includes/script-loader.php
@@ -435,12 +435,13 @@ function wp_default_scripts( &$scripts ) {
 		 * @param string The emoji base URL.
 		 */
 		'baseUrl' => apply_filters( 'emoji_url', '//s0.wp.com/wp-content/mu-plugins/emoji/twemoji/72x72' ),
+
 		/**
 		 * Filter the extension of the emoji files.
 		 *
 		 * @since 4.2.0
 		 *
-		 * @param string The emoji extension.
+		 * @param string The emoji extension. Default .png.
 		 */
 		'ext'      => apply_filters( 'emoji_ext', '.png' ),
 	) );