X-Git-Url: https://scripts.mit.edu/gitweb/autoinstalls/wordpress.git/blobdiff_plain/899389d1e4043331309c0433543419258b230b60..dc1231b7312fbdca99e9e887cc2bb35a28f85cdc:/wp-includes/taxonomy.php

diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php
index 7e386695..4328a366 100644
--- a/wp-includes/taxonomy.php
+++ b/wp-includes/taxonomy.php
@@ -2,9 +2,10 @@
 /**
  * Taxonomy API
  *
+ * @since 2.3.0
+ *
  * @package WordPress
  * @subpackage Taxonomy
- * @since 2.3.0
  */
 
 //
@@ -15,8 +16,12 @@
  * Creates the initial taxonomies.
  *
  * This function fires twice: in wp-settings.php before plugins are loaded (for
- * backwards compatibility reasons), and again on the 'init' action. We must avoid
- * registering rewrite rules before the 'init' action.
+ * backwards compatibility reasons), and again on the {@see 'init'} action. We must
+ * avoid registering rewrite rules before the {@see 'init'} action.
+ *
+ * @since 2.8.0
+ *
+ * @global WP_Rewrite $wp_rewrite The WordPress rewrite class.
  */
 function create_initial_taxonomies() {
 	global $wp_rewrite;
@@ -129,16 +134,20 @@ function create_initial_taxonomies() {
 }
 
 /**
- * Get a list of registered taxonomy objects.
+ * Retrieves a list of registered taxonomy names or objects.
  *
  * @since 3.0.0
- * @uses $wp_taxonomies
  *
- * @param array $args An array of key => value arguments to match against the taxonomy objects.
- * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
- * @param string $operator The logical operation to perform. 'or' means only one element
- *  from the array needs to match; 'and' means all elements must match. The default is 'and'.
- * @return array A list of taxonomy names or objects
+ * @global array $wp_taxonomies The registered taxonomies.
+ *
+ * @param array  $args     Optional. An array of `key => value` arguments to match against the taxonomy objects.
+ *                         Default empty array.
+ * @param string $output   Optional. The type of output to return in the array. Accepts either taxonomy 'names'
+ *                         or 'objects'. Default 'names'.
+ * @param string $operator Optional. The logical operation to perform. Accepts 'and' or 'or'. 'or' means only
+ *                         one element from the array needs to match; 'and' means all elements must match.
+ *                         Default 'and'.
+ * @return array A list of taxonomy names or objects.
  */
 function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' ) {
 	global $wp_taxonomies;
@@ -159,13 +168,14 @@ function get_taxonomies( $args = array(), $output = 'names', $operator = 'and' )
  *
  * @since 2.3.0
  *
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
  *
- * @param array|string|object $object Name of the type of taxonomy object, or an object (row from posts)
- * @param string $output The type of output to return, either taxonomy 'names' or 'objects'. 'names' is the default.
+ * @param array|string|WP_Post $object Name of the type of taxonomy object, or an object (row from posts)
+ * @param string               $output Optional. The type of output to return in the array. Accepts either
+ *                                     taxonomy 'names' or 'objects'. Default 'names'.
  * @return array The names of all taxonomy of $object_type.
  */
-function get_object_taxonomies($object, $output = 'names') {
+function get_object_taxonomies( $object, $output = 'names' ) {
 	global $wp_taxonomies;
 
 	if ( is_object($object) ) {
@@ -197,10 +207,10 @@ function get_object_taxonomies($object, $output = 'names') {
  *
  * @since 2.3.0
  *
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
  *
- * @param string $taxonomy Name of taxonomy object to return
- * @return object|bool The Taxonomy Object or false if $taxonomy doesn't exist
+ * @param string $taxonomy Name of taxonomy object to return.
+ * @return object|false The Taxonomy Object or false if $taxonomy doesn't exist.
  */
 function get_taxonomy( $taxonomy ) {
 	global $wp_taxonomies;
@@ -218,9 +228,9 @@ function get_taxonomy( $taxonomy ) {
  *
  * @since 3.0.0
  *
- * @uses $wp_taxonomies
+ * @global array $wp_taxonomies The registered taxonomies.
  *
- * @param string $taxonomy Name of taxonomy object
+ * @param string $taxonomy Name of taxonomy object.
  * @return bool Whether the taxonomy exists.
  */
 function taxonomy_exists( $taxonomy ) {
@@ -239,8 +249,8 @@ function taxonomy_exists( $taxonomy ) {
  *
  * @since 2.3.0
  *
- * @param string $taxonomy Name of taxonomy object
- * @return bool Whether the taxonomy is hierarchical
+ * @param string $taxonomy Name of taxonomy object.
+ * @return bool Whether the taxonomy is hierarchical.
  */
 function is_taxonomy_hierarchical($taxonomy) {
 	if ( ! taxonomy_exists($taxonomy) )
@@ -309,16 +319,18 @@ function is_taxonomy_hierarchical($taxonomy) {
  *     * Defaults to _update_generic_term_count() for taxonomies attached to other object types, such as links.
  * - _builtin - true if this taxonomy is a native or "built-in" taxonomy. THIS IS FOR INTERNAL USE ONLY!
  *
+ * @todo Document $args as a hash notation.
+ *
  * @since 2.3.0
  * @since 4.2.0 Introduced `show_in_quick_edit` argument.
  *
  * @global array $wp_taxonomies Registered taxonomies.
  * @global WP    $wp            WP instance.
  *
- * @param string $taxonomy Taxonomy key, must not exceed 32 characters.
+ * @param string       $taxonomy    Taxonomy key, must not exceed 32 characters.
  * @param array|string $object_type Name of the object type for the taxonomy object.
- * @param array|string $args See optional args description above.
- * @return null|WP_Error WP_Error if errors, otherwise null.
+ * @param array|string $args        See optional args description above.
+ * @return WP_Error|void WP_Error, if errors.
  */
 function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
 	global $wp_taxonomies, $wp;
@@ -460,14 +472,18 @@ function register_taxonomy( $taxonomy, $object_type, $args = array() ) {
  * - add_or_remove_items - This string isn't used on hierarchical taxonomies. Default is "Add or remove tags", used in the meta box when JavaScript is disabled.
  * - choose_from_most_used - This string isn't used on hierarchical taxonomies. Default is "Choose from the most used tags", used in the meta box.
  * - not_found - Default is "No tags found"/"No categories found", used in the meta box and taxonomy list table.
+ * - no_terms - Default is "No tags"/"No categories", used in the posts and media list tables.
  *
  * Above, the first default value is for non-hierarchical taxonomies (like tags) and the second one is for hierarchical taxonomies (like categories).
  *
+ * @todo Better documentation for the labels array.
+ *
  * @since 3.0.0
- * @param object $tax Taxonomy object
- * @return object object with all the labels as member variables
+ * @since 4.3.0 Added the `no_terms` label.
+ *
+ * @param object $tax Taxonomy object.
+ * @return object object with all the labels as member variables.
  */
-
 function get_taxonomy_labels( $tax ) {
 	$tax->labels = (array) $tax->labels;
 
@@ -494,6 +510,7 @@ function get_taxonomy_labels( $tax ) {
 		'add_or_remove_items' => array( __( 'Add or remove tags' ), null ),
 		'choose_from_most_used' => array( __( 'Choose from the most used tags' ), null ),
 		'not_found' => array( __( 'No tags found.' ), __( 'No categories found.' ) ),
+		'no_terms' => array( __( 'No tags' ), __( 'No categories' ) ),
 	);
 	$nohier_vs_hier_defaults['menu_name'] = $nohier_vs_hier_defaults['name'];
 
@@ -504,11 +521,12 @@ function get_taxonomy_labels( $tax ) {
  * Add an already registered taxonomy to an object type.
  *
  * @since 3.0.0
- * @uses $wp_taxonomies Modifies taxonomy object
  *
- * @param string $taxonomy Name of taxonomy object
- * @param string $object_type Name of the object type
- * @return bool True if successful, false if not
+ * @global array $wp_taxonomies The registered taxonomies.
+ *
+ * @param string $taxonomy    Name of taxonomy object.
+ * @param string $object_type Name of the object type.
+ * @return bool True if successful, false if not.
  */
 function register_taxonomy_for_object_type( $taxonomy, $object_type) {
 	global $wp_taxonomies;
@@ -522,6 +540,9 @@ function register_taxonomy_for_object_type( $taxonomy, $object_type) {
 	if ( ! in_array( $object_type, $wp_taxonomies[$taxonomy]->object_type ) )
 		$wp_taxonomies[$taxonomy]->object_type[] = $object_type;
 
+	// Filter out empties.
+	$wp_taxonomies[ $taxonomy ]->object_type = array_filter( $wp_taxonomies[ $taxonomy ]->object_type );
+
 	return true;
 }
 
@@ -530,6 +551,8 @@ function register_taxonomy_for_object_type( $taxonomy, $object_type) {
  *
  * @since 3.7.0
  *
+ * @global array $wp_taxonomies The registered taxonomies.
+ *
  * @param string $taxonomy    Name of taxonomy object.
  * @param string $object_type Name of the object type.
  * @return bool True if successful, false if not.
@@ -574,10 +597,10 @@ function unregister_taxonomy_for_object_type( $taxonomy, $object_type ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param int|array $term_ids Term id or array of term ids of terms that will be used
- * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names
- * @param array|string $args Change the order of the object_ids, either ASC or DESC
- * @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success
+ * @param int|array    $term_ids   Term id or array of term ids of terms that will be used.
+ * @param string|array $taxonomies String of taxonomy name or Array of string values of taxonomy names.
+ * @param array|string $args       Change the order of the object_ids, either ASC or DESC.
+ * @return WP_Error|array If the taxonomy does not exist, then WP_Error will be returned. On success.
  *	the array can be empty meaning that there are no $object_ids found or it will return the $object_ids found.
  */
 function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
@@ -620,7 +643,7 @@ function get_objects_in_term( $term_ids, $taxonomies, $args = array() ) {
  *
  * @see WP_Tax_Query
  *
- * @param array $tax_query A compact tax query
+ * @param array  $tax_query         A compact tax query
  * @param string $primary_table
  * @param string $primary_id_column
  * @return array
@@ -633,7 +656,7 @@ function get_tax_sql( $tax_query, $primary_table, $primary_id_column ) {
 /**
  * Class for generating SQL clauses that filter a primary query according to object taxonomy terms.
  *
- * `WP_Tax_Query` is a helper that allows primary query classes, such as {@see WP_Query}, to filter
+ * `WP_Tax_Query` is a helper that allows primary query classes, such as WP_Query, to filter
  * their results by object metadata, by generating `JOIN` and `WHERE` subclauses to be attached
  * to the primary SQL query string.
  *
@@ -665,6 +688,8 @@ class WP_Tax_Query {
 	 * Standard response when the query should not return any rows.
 	 *
 	 * @since 3.2.0
+	 *
+	 * @static
 	 * @access private
 	 * @var string
 	 */
@@ -683,7 +708,7 @@ class WP_Tax_Query {
 	 * Terms and taxonomies fetched by this query.
 	 *
 	 * We store this data in a flat array because they are referenced in a
-	 * number of places by {@see WP_Query}.
+	 * number of places by WP_Query.
 	 *
 	 * @since 4.1.0
 	 * @access public
@@ -848,6 +873,8 @@ class WP_Tax_Query {
 	 * determined, by process of elimination, to be a higher-order query.
 	 *
 	 * @since 4.1.0
+	 *
+	 * @static
 	 * @access protected
 	 *
 	 * @param array $query Tax query arguments.
@@ -861,6 +888,8 @@ class WP_Tax_Query {
 	 * Generates SQL clauses to be appended to a main query.
 	 *
 	 * @since 3.1.0
+	 *
+	 * @static
 	 * @access public
 	 *
 	 * @param string $primary_table     Database table where the object being filtered is stored (eg wp_users).
@@ -882,7 +911,7 @@ class WP_Tax_Query {
 	/**
 	 * Generate SQL clauses to be appended to a main query.
 	 *
-	 * Called by the public {@see WP_Tax_Query::get_sql()}, this method
+	 * Called by the public WP_Tax_Query::get_sql(), this method
 	 * is abstracted out to maintain parity with the other Query classes.
 	 *
 	 * @since 4.1.0
@@ -1001,7 +1030,9 @@ class WP_Tax_Query {
 	 * @since 4.1.0
 	 * @access public
 	 *
-	 * @param array $clause       Query clause, passed by reference
+	 * @global wpdb $wpdb The WordPress database abstraction object.
+	 *
+	 * @param array $clause       Query clause, passed by reference.
 	 * @param array $parent_query Parent query array.
 	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
@@ -1018,7 +1049,7 @@ class WP_Tax_Query {
 			'join'  => array(),
 		);
 
-		$join = '';
+		$join = $where = '';
 
 		$this->clean_query( $clause );
 
@@ -1119,7 +1150,7 @@ class WP_Tax_Query {
 	 * An existing alias is compatible if (a) it is a sibling of `$clause`
 	 * (ie, it's under the scope of the same relation), and (b) the combination
 	 * of operator and relation between the clauses allows for a shared table
-	 * join. In the case of {@see WP_Tax_Query}, this only applies to 'IN'
+	 * join. In the case of WP_Tax_Query, this only applies to 'IN'
 	 * clauses that are connected by the relation 'OR'.
 	 *
 	 * @since 4.1.0
@@ -1127,7 +1158,7 @@ class WP_Tax_Query {
 	 *
 	 * @param array       $clause       Query clause.
 	 * @param array       $parent_query Parent query of $clause.
-	 * @return string|bool Table alias if found, otherwise false.
+	 * @return string|false Table alias if found, otherwise false.
 	 */
 	protected function find_compatible_table_alias( $clause, $parent_query ) {
 		$alias = false;
@@ -1209,9 +1240,11 @@ class WP_Tax_Query {
 	 *
 	 * @since 3.2.0
 	 *
+	 * @global wpdb $wpdb The WordPress database abstraction object.
+	 *
 	 * @param array  &$query          The single query.
 	 * @param string $resulting_field The resulting field. Accepts 'slug', 'name', 'term_taxonomy_id',
-	 *                                or 'term_id'. Default: 'term_id'.
+	 *                                or 'term_id'. Default 'term_id'.
 	 */
 	public function transform_query( &$query, $resulting_field ) {
 		global $wpdb;
@@ -1290,38 +1323,38 @@ class WP_Tax_Query {
  * term object, and the taxonomy name as parameters. Both hooks are expected to
  * return a Term object.
  *
- * 'get_term' hook - Takes two parameters the term Object and the taxonomy name.
+ * {@see 'get_term'} hook - Takes two parameters the term Object and the taxonomy name.
  * Must return term object. Used in get_term() as a catch-all filter for every
  * $term.
  *
- * 'get_$taxonomy' hook - Takes two parameters the term Object and the taxonomy
+ * {@see 'get_$taxonomy'} hook - Takes two parameters the term Object and the taxonomy
  * name. Must return term object. $taxonomy will be the taxonomy name, so for
  * example, if 'category', it would be 'get_category' as the filter name. Useful
  * for custom taxonomies or plugging into default taxonomies.
  *
+ * @todo Better formatting for DocBlock
+ *
  * @since 2.3.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
  *
- * @param int|object $term If integer, will get from database. If object will apply filters and return $term.
- * @param string $taxonomy Taxonomy name that $term is part of.
- * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
- * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
- * @return mixed|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
+ * @param int|object $term     If integer, will get from database. If object will apply filters and return $term.
+ * @param string     $taxonomy Taxonomy name that $term is part of.
+ * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
+ * @return object|array|null|WP_Error Term Row from database. Will return null if $term is empty. If taxonomy does not
  * exist then WP_Error will be returned.
  */
 function get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') {
 	global $wpdb;
 
-	if ( empty($term) ) {
-		$error = new WP_Error('invalid_term', __('Empty Term'));
-		return $error;
+	if ( empty( $term ) ) {
+		return new WP_Error( 'invalid_term', __( 'Empty Term' ) );
 	}
 
-	if ( ! taxonomy_exists($taxonomy) ) {
-		$error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
-		return $error;
+	if ( ! taxonomy_exists( $taxonomy ) ) {
+		return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
 	}
 
 	if ( is_object($term) && empty($term->filter) ) {
@@ -1389,17 +1422,20 @@ function get_term($term, $taxonomy, $output = OBJECT, $filter = 'raw') {
  * If $value does not exist, the return value will be false. If $taxonomy exists
  * and $field and $value combinations exist, the Term will be returned.
  *
+ * @todo Better formatting for DocBlock.
+ *
  * @since 2.3.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  * @see sanitize_term_field() The $context param lists the available values for get_term_by() $filter param.
  *
- * @param string $field Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
- * @param string|int $value Search for this term value
- * @param string $taxonomy Taxonomy Name
- * @param string $output Constant OBJECT, ARRAY_A, or ARRAY_N
- * @param string $filter Optional, default is raw or no WordPress defined filter will applied.
- * @return mixed Term Row from database. Will return false if $taxonomy does not exist or $term was not found.
+ * @param string     $field    Either 'slug', 'name', 'id' (term_id), or 'term_taxonomy_id'
+ * @param string|int $value    Search for this term value
+ * @param string     $taxonomy Taxonomy Name
+ * @param string     $output   Constant OBJECT, ARRAY_A, or ARRAY_N
+ * @param string     $filter   Optional, default is raw or no WordPress defined filter will applied.
+ * @return object|array|null|WP_Error|false Term Row from database.
+ *                                          Will return false if $taxonomy does not exist or $term was not found.
  */
 function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw') {
 	global $wpdb;
@@ -1461,11 +1497,9 @@ function get_term_by($field, $value, $taxonomy, $output = OBJECT, $filter = 'raw
  *
  * @since 2.3.0
  *
- * @global wpdb $wpdb WordPress database abstraction object.
- *
- * @param string $term_id ID of Term to get children
- * @param string $taxonomy Taxonomy Name
- * @return array|WP_Error List of Term IDs. WP_Error returned if $taxonomy does not exist
+ * @param string $term_id  ID of Term to get children.
+ * @param string $taxonomy Taxonomy Name.
+ * @return array|WP_Error List of Term IDs. WP_Error returned if `$taxonomy` does not exist.
  */
 function get_term_children( $term_id, $taxonomy ) {
 	if ( ! taxonomy_exists($taxonomy) )
@@ -1501,11 +1535,11 @@ function get_term_children( $term_id, $taxonomy ) {
  *
  * @since 2.3.0
  *
- * @param string $field Term field to fetch
- * @param int $term Term ID
- * @param string $taxonomy Taxonomy Name
- * @param string $context Optional, default is display. Look at sanitize_term_field() for available options.
- * @return mixed Will return an empty string if $term is not an object or if $field is not set in $term.
+ * @param string $field    Term field to fetch.
+ * @param int    $term     Term ID.
+ * @param string $taxonomy Taxonomy Name.
+ * @param string $context  Optional, default is display. Look at sanitize_term_field() for available options.
+ * @return string|int|null|WP_Error Will return an empty string if $term is not an object or if $field is not set in $term.
  */
 function get_term_field( $field, $term, $taxonomy, $context = 'display' ) {
 	$term = (int) $term;
@@ -1530,9 +1564,9 @@ function get_term_field( $field, $term, $taxonomy, $context = 'display' ) {
  *
  * @since 2.3.0
  *
- * @param int|object $id Term ID or Object
- * @param string $taxonomy Taxonomy Name
- * @return mixed|null|WP_Error Will return empty string if $term is not an object.
+ * @param int|object $id       Term ID or object.
+ * @param string     $taxonomy Taxonomy name.
+ * @return string|int|null|WP_Error Will return empty string if $term is not an object.
  */
 function get_term_to_edit( $id, $taxonomy ) {
 	$term = get_term( $id, $taxonomy );
@@ -1552,21 +1586,22 @@ function get_term_to_edit( $id, $taxonomy ) {
  * You can fully inject any customizations to the query before it is sent, as
  * well as control the output with a filter.
  *
- * The 'get_terms' filter will be called when the cache has the term and will
+ * The {@see 'get_terms'} filter will be called when the cache has the term and will
  * pass the found term along with the array of $taxonomies and array of $args.
  * This filter is also called before the array of terms is passed and will pass
  * the array of terms, along with the $taxonomies and $args.
  *
- * The 'list_terms_exclusions' filter passes the compiled exclusions along with
+ * The {@see 'list_terms_exclusions'} filter passes the compiled exclusions along with
  * the $args.
  *
- * The 'get_terms_orderby' filter passes the ORDER BY clause for the query
+ * The {@see 'get_terms_orderby'} filter passes the `ORDER BY` clause for the query
  * along with the $args array.
  *
  * @since 2.3.0
  * @since 4.2.0 Introduced 'name' and 'childless' parameters.
  *
- * @global wpdb $wpdb WordPress database abstraction object.
+ * @global wpdb  $wpdb WordPress database abstraction object.
+ * @global array $wp_filter
  *
  * @param string|array $taxonomies Taxonomy name or list of Taxonomy names.
  * @param array|string $args {
@@ -1617,7 +1652,7 @@ function get_term_to_edit( $id, $taxonomy ) {
  *     @type string       $cache_domain      Unique cache key to be produced when this query is stored in an
  *                                           object cache. Default is 'core'.
  * }
- * @return array|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies
+ * @return array|int|WP_Error List of Term Objects and their children. Will return WP_Error, if any of $taxonomies
  *                        do not exist.
  */
 function get_terms( $taxonomies, $args = '' ) {
@@ -1631,8 +1666,7 @@ function get_terms( $taxonomies, $args = '' ) {
 
 	foreach ( $taxonomies as $taxonomy ) {
 		if ( ! taxonomy_exists($taxonomy) ) {
-			$error = new WP_Error('invalid_taxonomy', __('Invalid taxonomy'));
-			return $error;
+			return new WP_Error( 'invalid_taxonomy', __( 'Invalid taxonomy' ) );
 		}
 	}
 
@@ -1676,7 +1710,7 @@ function get_terms( $taxonomies, $args = '' ) {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param array $args       An array of arguments.
+	 * @param array $args       An array of get_term() arguments.
 	 * @param array $taxonomies An array of taxonomies.
 	 */
 	$args = apply_filters( 'get_terms_args', $args, $taxonomies );
@@ -1708,7 +1742,7 @@ function get_terms( $taxonomies, $args = '' ) {
 		}
 	}
 
-	// $args can be whatever, only use the args defined in defaults to compute the key
+	// $args can be whatever, only use the args defined in defaults to compute the key.
 	$filter_key = ( has_filter('list_terms_exclusions') ) ? serialize($GLOBALS['wp_filter']['list_terms_exclusions']) : '';
 	$key = md5( serialize( wp_array_slice_assoc( $args, array_keys( $defaults ) ) ) . serialize( $taxonomies ) . $filter_key );
 	$last_changed = wp_cache_get( 'last_changed', 'terms' );
@@ -1727,10 +1761,9 @@ function get_terms( $taxonomies, $args = '' ) {
 		 *
 		 * @param array $cache      Cached array of terms for the given taxonomy.
 		 * @param array $taxonomies An array of taxonomies.
-		 * @param array $args       An array of arguments to get terms.
+		 * @param array $args       An array of get_terms() arguments.
 		 */
-		$cache = apply_filters( 'get_terms', $cache, $taxonomies, $args );
-		return $cache;
+		return apply_filters( 'get_terms', $cache, $taxonomies, $args );
 	}
 
 	$_orderby = strtolower( $args['orderby'] );
@@ -1754,12 +1787,13 @@ function get_terms( $taxonomies, $args = '' ) {
 	} else {
 		$orderby = 't.name';
 	}
+
 	/**
 	 * Filter the ORDERBY clause of the terms query.
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param string $orderby    ORDERBY clause of the terms query.
+	 * @param string $orderby    `ORDERBY` clause of the terms query.
 	 * @param array  $args       An array of terms query arguments.
 	 * @param array  $taxonomies An array of taxonomies.
 	 */
@@ -1831,7 +1865,7 @@ function get_terms( $taxonomies, $args = '' ) {
 	 *
 	 * @since 2.3.0
 	 *
-	 * @param string $exclusions NOT IN clause of the terms query.
+	 * @param string $exclusions `NOT IN` clause of the terms query.
 	 * @param array  $args       An array of terms query arguments.
 	 * @param array  $taxonomies An array of taxonomies.
 	 */
@@ -1842,13 +1876,12 @@ function get_terms( $taxonomies, $args = '' ) {
 	}
 
 	if ( ! empty( $args['name'] ) ) {
-		if ( is_array( $args['name'] ) ) {
-			$name = array_map( 'sanitize_text_field', $args['name'] );
-			$where .= " AND t.name IN ('" . implode( "', '", array_map( 'esc_sql', $name ) ) . "')";
-		} else {
-			$name = sanitize_text_field( $args['name'] );
-			$where .= $wpdb->prepare( " AND t.name = %s", $name );
+		$names = (array) $args['name'];
+		foreach ( $names as &$_name ) {
+			$_name = sanitize_term_field( 'name', $_name, 0, reset( $taxonomies ), 'db' );
 		}
+
+		$where .= " AND t.name IN ('" . implode( "', '", array_map( 'esc_sql', $names ) ) . "')";
 	}
 
 	if ( ! empty( $args['slug'] ) ) {
@@ -1885,7 +1918,7 @@ function get_terms( $taxonomies, $args = '' ) {
 	$number = $args['number'];
 	$offset = $args['offset'];
 
-	// don't limit the query results when we have to descend the family tree
+	// Don't limit the query results when we have to descend the family tree.
 	if ( $number && ! $hierarchical && ! $child_of && '' === $parent ) {
 		if ( $offset ) {
 			$limits = 'LIMIT ' . $offset . ',' . $number;
@@ -1960,6 +1993,7 @@ function get_terms( $taxonomies, $args = '' ) {
 	 * @param array $args       An array of terms query arguments.
 	 */
 	$clauses = apply_filters( 'terms_clauses', compact( $pieces ), $taxonomies, $args );
+
 	$fields = isset( $clauses[ 'fields' ] ) ? $clauses[ 'fields' ] : '';
 	$join = isset( $clauses[ 'join' ] ) ? $clauses[ 'join' ] : '';
 	$where = isset( $clauses[ 'where' ] ) ? $clauses[ 'where' ] : '';
@@ -1970,8 +2004,7 @@ function get_terms( $taxonomies, $args = '' ) {
 	$query = "SELECT $fields FROM $wpdb->terms AS t $join WHERE $where $orderby $order $limits";
 
 	if ( 'count' == $_fields ) {
-		$term_count = $wpdb->get_var($query);
-		return $term_count;
+		return $wpdb->get_var( $query );
 	}
 
 	$terms = $wpdb->get_results($query);
@@ -1983,8 +2016,7 @@ function get_terms( $taxonomies, $args = '' ) {
 		wp_cache_add( $cache_key, array(), 'terms', DAY_IN_SECONDS );
 
 		/** This filter is documented in wp-includes/taxonomy.php */
-		$terms = apply_filters( 'get_terms', array(), $taxonomies, $args );
-		return $terms;
+		return apply_filters( 'get_terms', array(), $taxonomies, $args );
 	}
 
 	if ( $child_of ) {
@@ -2017,7 +2049,7 @@ function get_terms( $taxonomies, $args = '' ) {
 					}
 				}
 
-				// It really is empty
+				// It really is empty.
 				unset($terms[$k]);
 			}
 		}
@@ -2057,8 +2089,7 @@ function get_terms( $taxonomies, $args = '' ) {
 	wp_cache_add( $cache_key, $terms, 'terms', DAY_IN_SECONDS );
 
 	/** This filter is documented in wp-includes/taxonomy */
-	$terms = apply_filters( 'get_terms', $terms, $taxonomies, $args );
-	return $terms;
+	return apply_filters( 'get_terms', $terms, $taxonomies, $args );
 }
 
 /**
@@ -2070,9 +2101,9 @@ function get_terms( $taxonomies, $args = '' ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param int|string $term The term to check
- * @param string $taxonomy The taxonomy name to use
- * @param int $parent Optional. ID of parent term under which to confine the exists search.
+ * @param int|string $term     The term to check
+ * @param string     $taxonomy The taxonomy name to use
+ * @param int        $parent   Optional. ID of parent term under which to confine the exists search.
  * @return mixed Returns null if the term does not exist. Returns the term ID
  *               if no taxonomy is specified and the term ID exists. Returns
  *               an array of the term ID and the term taxonomy ID the taxonomy
@@ -2134,10 +2165,10 @@ function term_exists( $term, $taxonomy = '', $parent = null ) {
  *
  * @since 3.4.0
  *
- * @param int|object $term1 ID or object to check if this is the parent term.
- * @param int|object $term2 The child term.
- * @param string $taxonomy Taxonomy name that $term1 and $term2 belong to.
- * @return bool Whether $term2 is child of $term1
+ * @param int|object $term1    ID or object to check if this is the parent term.
+ * @param int|object $term2    The child term.
+ * @param string     $taxonomy Taxonomy name that $term1 and `$term2` belong to.
+ * @return bool Whether `$term2` is a child of `$term1`.
  */
 function term_is_ancestor_of( $term1, $term2, $taxonomy ) {
 	if ( ! isset( $term1->term_id ) )
@@ -2164,13 +2195,13 @@ function term_is_ancestor_of( $term1, $term2, $taxonomy ) {
  *
  * @since 2.3.0
  *
- * @param array|object $term The term to check
- * @param string $taxonomy The taxonomy name to use
- * @param string $context Default is 'display'.
- * @return array|object Term with all fields sanitized
+ * @param array|object $term     The term to check.
+ * @param string       $taxonomy The taxonomy name to use.
+ * @param string       $context  Optional. Context in which to sanitize the term. Accepts 'edit', 'db',
+ *                               'display', 'attribute', or 'js'. Default 'display'.
+ * @return array|object Term with all fields sanitized.
  */
 function sanitize_term($term, $taxonomy, $context = 'display') {
-
 	$fields = array( 'term_id', 'name', 'description', 'slug', 'count', 'parent', 'term_group', 'term_taxonomy_id', 'object_id' );
 
 	$do_object = is_object( $term );
@@ -2210,14 +2241,13 @@ function sanitize_term($term, $taxonomy, $context = 'display') {
  *
  * @since 2.3.0
  *
- * @global wpdb $wpdb WordPress database abstraction object.
- *
- * @param string $field Term field to sanitize
- * @param string $value Search for this term value
- * @param int $term_id Term ID
- * @param string $taxonomy Taxonomy Name
- * @param string $context Either edit, db, display, attribute, or js.
- * @return mixed sanitized field
+ * @param string $field    Term field to sanitize.
+ * @param string $value    Search for this term value.
+ * @param int    $term_id  Term ID.
+ * @param string $taxonomy Taxonomy Name.
+ * @param string $context  Context in which to sanitize the term field. Accepts 'edit', 'db', 'display',
+ *                         'attribute', or 'js'.
+ * @return mixed Sanitized field.
  */
 function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
 	$int_fields = array( 'parent', 'term_id', 'count', 'term_group', 'term_taxonomy_id', 'object_id' );
@@ -2257,6 +2287,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
 		 * @param int   $term_id Term ID.
 		 */
 		$value = apply_filters( "edit_{$taxonomy}_{$field}", $value, $term_id );
+
 		if ( 'description' == $field )
 			$value = esc_html($value); // textarea_escaped
 		else
@@ -2286,6 +2317,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
 		 * @param mixed $value Value of the taxonomy field.
 		 */
 		$value = apply_filters( "pre_{$taxonomy}_{$field}", $value );
+
 		// Back compat filters
 		if ( 'slug' == $field ) {
 			/**
@@ -2317,7 +2349,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
 		/**
 		 * Filter the taxonomy field for use in RSS.
 		 *
-		 * The dynamic portions of the hook name, `$taxonomy`, and $field, refer
+		 * The dynamic portions of the hook name, `$taxonomy`, and `$field`, refer
 		 * to the taxonomy slug and field name, respectively.
 		 *
 		 * @since 2.3.0
@@ -2345,7 +2377,7 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
 		/**
 		 * Filter the taxonomy field sanitized for display.
 		 *
-		 * The dynamic portions of the filter name, `$taxonomy`, and $field, refer
+		 * The dynamic portions of the filter name, `$taxonomy`, and `$field`, refer
 		 * to the taxonomy slug and taxonomy field, respectively.
 		 *
 		 * @since 2.3.0
@@ -2370,11 +2402,13 @@ function sanitize_term_field($field, $value, $term_id, $taxonomy, $context) {
  *
  * Default $args is 'hide_empty' which can be 'hide_empty=true' or array('hide_empty' => true).
  *
+ * @todo Document $args as a hash notation.
+ *
  * @since 2.3.0
  *
- * @param string $taxonomy Taxonomy name
- * @param array|string $args Overwrite defaults. See get_terms()
- * @return int|WP_Error How many terms are in $taxonomy. WP_Error if $taxonomy does not exist.
+ * @param string       $taxonomy Taxonomy name
+ * @param array|string $args     Overwrite defaults. See get_terms()
+ * @return array|int|WP_Error How many terms are in $taxonomy. WP_Error if $taxonomy does not exist.
  */
 function wp_count_terms( $taxonomy, $args = array() ) {
 	$defaults = array('hide_empty' => false);
@@ -2400,7 +2434,7 @@ function wp_count_terms( $taxonomy, $args = array() ) {
  *
  * @since 2.3.0
  *
- * @param int $object_id The term Object Id that refers to the term
+ * @param int          $object_id  The term Object Id that refers to the term.
  * @param string|array $taxonomies List of Taxonomy Names or single Taxonomy name.
  */
 function wp_delete_object_term_relationships( $object_id, $taxonomies ) {
@@ -2422,20 +2456,22 @@ function wp_delete_object_term_relationships( $object_id, $taxonomies ) {
  * If the term is a parent of other terms, then the children will be updated to
  * that term's parent.
  *
- * The $args 'default' will only override the terms found, if there is only one
+ * The `$args` 'default' will only override the terms found, if there is only one
  * term found. Any other and the found terms are used.
  *
  * The $args 'force_default' will force the term supplied as default to be
  * assigned even if the object was not going to be termless
  *
+ * @todo Document $args as a hash notation.
+ *
  * @since 2.3.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param int $term Term ID
- * @param string $taxonomy Taxonomy Name
- * @param array|string $args Optional. Change 'default' term id and override found term ids.
- * @return bool|WP_Error Returns false if not term; true if completes delete action.
+ * @param int          $term     Term ID.
+ * @param string       $taxonomy Taxonomy Name.
+ * @param array|string $args     Optional. Change 'default' term id and override found term ids.
+ * @return bool|int|WP_Error Returns false if not term; true if completes delete action.
  */
 function wp_delete_term( $term, $taxonomy, $args = array() ) {
 	global $wpdb;
@@ -2498,6 +2534,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) {
 		 * @param array $edit_tt_ids An array of term taxonomy IDs for the given term.
 		 */
 		do_action( 'edit_term_taxonomies', $edit_tt_ids );
+
 		$wpdb->update( $wpdb->term_taxonomy, compact( 'parent' ), array( 'parent' => $term_obj->term_id) + compact( 'taxonomy' ) );
 
 		// Clean the cache for all child terms.
@@ -2529,7 +2566,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) {
 		wp_set_object_terms($object, $terms, $taxonomy);
 	}
 
-	// Clean the relationship caches for all object types using this term
+	// Clean the relationship caches for all object types using this term.
 	$tax_object = get_taxonomy( $taxonomy );
 	foreach ( $tax_object->object_type as $object_type )
 		clean_object_term_cache( $objects, $object_type );
@@ -2586,7 +2623,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) {
 	 * @param int     $term         Term ID.
 	 * @param int     $tt_id        Term taxonomy ID.
 	 * @param mixed   $deleted_term Copy of the already-deleted term, in the form specified
-	 *                              by the parent function. {@see WP_Error} otherwise.
+	 *                              by the parent function. WP_Error otherwise.
 	 */
 	do_action( "delete_$taxonomy", $term, $tt_id, $deleted_term );
 
@@ -2599,7 +2636,7 @@ function wp_delete_term( $term, $taxonomy, $args = array() ) {
  * @since 2.0.0
  *
  * @param int $cat_ID
- * @return mixed Returns true if completes delete action; false if term doesn't exist;
+ * @return bool|int|WP_Error Returns true if completes delete action; false if term doesn't exist;
  * 	Zero on attempted deletion of default Category; WP_Error object is also a possibility.
  */
 function wp_delete_category( $cat_ID ) {
@@ -2678,11 +2715,11 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) {
 
 	if ( in_array( $orderby, array( 'term_id', 'name', 'slug', 'term_group' ) ) ) {
 		$orderby = "t.$orderby";
-	} else if ( in_array( $orderby, array( 'count', 'parent', 'taxonomy', 'term_taxonomy_id' ) ) ) {
+	} elseif ( in_array( $orderby, array( 'count', 'parent', 'taxonomy', 'term_taxonomy_id' ) ) ) {
 		$orderby = "tt.$orderby";
-	} else if ( 'term_order' === $orderby ) {
+	} elseif ( 'term_order' === $orderby ) {
 		$orderby = 'tr.term_order';
-	} else if ( 'none' === $orderby ) {
+	} elseif ( 'none' === $orderby ) {
 		$orderby = '';
 		$order = '';
 	} else {
@@ -2928,10 +2965,10 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
 				}
 
 				if ( $existing_term ) {
-					return new WP_Error( 'term_exists', __( 'A term with the name already exists with this parent.' ), $existing_term->term_id );
+					return new WP_Error( 'term_exists', __( 'A term with the name provided already exists with this parent.' ), $existing_term->term_id );
 				}
 			} else {
-				return new WP_Error( 'term_exists', __( 'A term with the name already exists in this taxonomy.' ), $name_match->term_id );
+				return new WP_Error( 'term_exists', __( 'A term with the name provided already exists in this taxonomy.' ), $name_match->term_id );
 			}
 		}
 	}
@@ -3022,13 +3059,19 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
 	 * Fires after a new term is created, and after the term cache has been cleaned.
 	 *
 	 * @since 2.3.0
+	 *
+	 * @param int    $term_id  Term ID.
+	 * @param int    $tt_id    Term taxonomy ID.
+	 * @param string $taxonomy Taxonomy slug.
 	 */
-	do_action( "created_term", $term_id, $tt_id, $taxonomy );
+	do_action( 'created_term', $term_id, $tt_id, $taxonomy );
 
 	/**
 	 * Fires after a new term in a specific taxonomy is created, and after the term
 	 * cache has been cleaned.
 	 *
+	 * The dynamic portion of the hook name, `$taxonomy`, refers to the taxonomy slug.
+	 *
 	 * @since 2.3.0
 	 *
 	 * @param int $term_id Term ID.
@@ -3052,6 +3095,8 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
  *
  * @since 2.3.0
  *
+ * @global wpdb $wpdb The WordPress database abstraction object.
+ *
  * @param int              $object_id The object to relate to.
  * @param array|int|string $terms     A single term slug, single term id, or array of either term slugs or ids.
  *                                    Will replace all existing related terms in this taxonomy.
@@ -3175,9 +3220,9 @@ function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
  *
  * @since 3.6.0
  *
- * @param int $object_id The ID of the object to which the terms will be added.
- * @param array|int|string $terms The slug(s) or ID(s) of the term(s) to add.
- * @param array|string $taxonomy Taxonomy name.
+ * @param int              $object_id The ID of the object to which the terms will be added.
+ * @param array|int|string $terms     The slug(s) or ID(s) of the term(s) to add.
+ * @param array|string     $taxonomy  Taxonomy name.
  * @return array|WP_Error Affected Term IDs
  */
 function wp_add_object_terms( $object_id, $terms, $taxonomy ) {
@@ -3191,9 +3236,9 @@ function wp_add_object_terms( $object_id, $terms, $taxonomy ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param int $object_id The ID of the object from which the terms will be removed.
- * @param array|int|string $terms The slug(s) or ID(s) of the term(s) to remove.
- * @param array|string $taxonomy Taxonomy name.
+ * @param int              $object_id The ID of the object from which the terms will be removed.
+ * @param array|int|string $terms     The slug(s) or ID(s) of the term(s) to remove.
+ * @param array|string     $taxonomy  Taxonomy name.
  * @return bool|WP_Error True on success, false or WP_Error on failure.
  */
 function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
@@ -3253,6 +3298,7 @@ function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
 		 * @param array $tt_ids    An array of term taxonomy IDs.
 		 */
 		do_action( 'deleted_term_relationships', $object_id, $tt_ids );
+
 		wp_update_term_count( $tt_ids, $taxonomy );
 
 		return (bool) $deleted;
@@ -3264,7 +3310,7 @@ function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
 /**
  * Will make slug unique, if it isn't already.
  *
- * The $slug has to be unique global to every taxonomy, meaning that one
+ * The `$slug` has to be unique global to every taxonomy, meaning that one
  * taxonomy term can't have a matching slug with another taxonomy term. Each
  * slug has to be globally unique for every taxonomy.
  *
@@ -3274,38 +3320,42 @@ function wp_remove_object_terms( $object_id, $terms, $taxonomy ) {
  * If that still doesn't return an unique slug, then it try to append a number
  * until it finds a number that is truly unique.
  *
- * The only purpose for $term is for appending a parent, if one exists.
+ * The only purpose for `$term` is for appending a parent, if one exists.
  *
  * @since 2.3.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param string $slug The string that will be tried for a unique slug
- * @param object $term The term object that the $slug will belong too
+ * @param string $slug The string that will be tried for a unique slug.
+ * @param object $term The term object that the `$slug` will belong to.
  * @return string Will return a true unique slug.
  */
-function wp_unique_term_slug($slug, $term) {
+function wp_unique_term_slug( $slug, $term ) {
 	global $wpdb;
 
-	if ( ! term_exists( $slug ) )
-		return $slug;
+	$needs_suffix = true;
+	$original_slug = $slug;
 
 	// As of 4.1, duplicate slugs are allowed as long as they're in different taxonomies.
-	if ( get_option( 'db_version' ) >= 30133 && ! get_term_by( 'slug', $slug, $term->taxonomy ) ) {
-		return $slug;
+	if ( ! term_exists( $slug ) || get_option( 'db_version' ) >= 30133 && ! get_term_by( 'slug', $slug, $term->taxonomy ) ) {
+		$needs_suffix = false;
 	}
 
-	// If the taxonomy supports hierarchy and the term has a parent, make the slug unique
-	// by incorporating parent slugs.
-	if ( is_taxonomy_hierarchical($term->taxonomy) && !empty($term->parent) ) {
+	/*
+	 * If the taxonomy supports hierarchy and the term has a parent, make the slug unique
+	 * by incorporating parent slugs.
+	 */
+	$parent_suffix = '';
+	if ( $needs_suffix && is_taxonomy_hierarchical( $term->taxonomy ) && ! empty( $term->parent ) ) {
 		$the_parent = $term->parent;
 		while ( ! empty($the_parent) ) {
 			$parent_term = get_term($the_parent, $term->taxonomy);
 			if ( is_wp_error($parent_term) || empty($parent_term) )
 				break;
-			$slug .= '-' . $parent_term->slug;
-			if ( ! term_exists( $slug ) )
-				return $slug;
+			$parent_suffix .= '-' . $parent_term->slug;
+			if ( ! term_exists( $slug . $parent_suffix ) ) {
+				break;
+			}
 
 			if ( empty($parent_term->parent) )
 				break;
@@ -3314,22 +3364,47 @@ function wp_unique_term_slug($slug, $term) {
 	}
 
 	// If we didn't get a unique slug, try appending a number to make it unique.
-	if ( ! empty( $term->term_id ) )
-		$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d", $slug, $term->term_id );
-	else
-		$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $slug );
 
-	if ( $wpdb->get_var( $query ) ) {
-		$num = 2;
-		do {
-			$alt_slug = $slug . "-$num";
-			$num++;
-			$slug_check = $wpdb->get_var( $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $alt_slug ) );
-		} while ( $slug_check );
-		$slug = $alt_slug;
+	/**
+	 * Filter whether the proposed unique term slug is bad.
+	 *
+	 * @since 4.3.0
+	 *
+	 * @param bool   $needs_suffix Whether the slug needs to be made unique with a suffix.
+	 * @param string $slug         The slug.
+	 * @param object $term         Term object.
+	 */
+	if ( apply_filters( 'wp_unique_term_slug_is_bad_slug', $needs_suffix, $slug, $term ) ) {
+		if ( $parent_suffix ) {
+			$slug .= $parent_suffix;
+		} else {
+			if ( ! empty( $term->term_id ) )
+				$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s AND term_id != %d", $slug, $term->term_id );
+			else
+				$query = $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $slug );
+
+			if ( $wpdb->get_var( $query ) ) {
+				$num = 2;
+				do {
+					$alt_slug = $slug . "-$num";
+					$num++;
+					$slug_check = $wpdb->get_var( $wpdb->prepare( "SELECT slug FROM $wpdb->terms WHERE slug = %s", $alt_slug ) );
+				} while ( $slug_check );
+				$slug = $alt_slug;
+			}
+		}
 	}
 
-	return $slug;
+	/**
+	 * Filter the unique term slug.
+	 *
+	 * @since 4.3.0
+	 *
+	 * @param string $slug          Unique term slug.
+	 * @param object $term          Term object.
+	 * @param string $original_slug Slug originally passed to the function for testing.
+	 */
+	return apply_filters( 'wp_unique_term_slug', $slug, $term, $original_slug );
 }
 
 /**
@@ -3350,16 +3425,16 @@ function wp_unique_term_slug($slug, $term) {
  * a WP_Error will be passed back. If you don't pass any slug, then a unique one
  * will be created for you.
  *
- * For what can be overrode in $args, check the term scheme can contain and stay
+ * For what can be overrode in `$args`, check the term scheme can contain and stay
  * away from the term keys.
  *
  * @since 2.3.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param int $term_id The ID of the term
- * @param string $taxonomy The context in which to relate the term to the object.
- * @param array|string $args Overwrite term field values
+ * @param int          $term_id  The ID of the term
+ * @param string       $taxonomy The context in which to relate the term to the object.
+ * @param array|string $args     Optional. Array of get_terms() arguments. Default empty array.
  * @return array|WP_Error Returns Term ID and Taxonomy Term ID
  */
 function wp_update_term( $term_id, $taxonomy, $args = array() ) {
@@ -3506,6 +3581,7 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
 	 * @param string $taxonomy Taxonomy slug.
 	 */
 	do_action( 'edit_term_taxonomy', $tt_id, $taxonomy );
+
 	$wpdb->update( $wpdb->term_taxonomy, compact( 'term_id', 'taxonomy', 'description', 'parent' ), array( 'term_taxonomy_id' => $tt_id ) );
 
 	/**
@@ -3518,7 +3594,7 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
 	 */
 	do_action( 'edited_term_taxonomy', $tt_id, $taxonomy );
 
-	// Clean the relationship caches for all object types using this term
+	// Clean the relationship caches for all object types using this term.
 	$objects = $wpdb->get_col( $wpdb->prepare( "SELECT object_id FROM $wpdb->term_relationships WHERE term_taxonomy_id = %d", $tt_id ) );
 	$tax_object = get_taxonomy( $taxonomy );
 	foreach ( $tax_object->object_type as $object_type ) {
@@ -3586,6 +3662,8 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) {
  *
  * @since 2.5.0
  *
+ * @staticvar bool $_defer
+ *
  * @param bool $defer Optional. Enable if true, disable if false.
  * @return bool Whether term counting is enabled or disabled.
  */
@@ -3613,10 +3691,10 @@ function wp_defer_term_counting($defer=null) {
  *
  * @since 2.3.0
  *
- * @global wpdb $wpdb WordPress database abstraction object.
+ * @staticvar array $_deferred
  *
- * @param int|array $terms The term_taxonomy_id of the terms
- * @param string $taxonomy The context of the term.
+ * @param int|array $terms    The term_taxonomy_id of the terms.
+ * @param string    $taxonomy The context of the term.
  * @return bool If no terms will return false, and if successful will return true.
  */
 function wp_update_term_count( $terms, $taxonomy, $do_deferred=false ) {
@@ -3650,9 +3728,9 @@ function wp_update_term_count( $terms, $taxonomy, $do_deferred=false ) {
  *
  * @since 2.5.0
  *
- * @param array $terms The term_taxonomy_id of terms to update.
+ * @param array  $terms    The term_taxonomy_id of terms to update.
  * @param string $taxonomy The context of the term.
- * @return bool Always true when complete.
+ * @return true Always true when complete.
  */
 function wp_update_term_count_now( $terms, $taxonomy ) {
 	$terms = array_map('intval', $terms);
@@ -3688,16 +3766,16 @@ function wp_update_term_count_now( $terms, $taxonomy ) {
 /**
  * Removes the taxonomy relationship to terms from the cache.
  *
- * Will remove the entire taxonomy relationship containing term $object_id. The
- * term IDs have to exist within the taxonomy $object_type for the deletion to
+ * Will remove the entire taxonomy relationship containing term `$object_id`. The
+ * term IDs have to exist within the taxonomy `$object_type` for the deletion to
  * take place.
  *
  * @since 2.3.0
  *
- * @see get_object_taxonomies() for more on $object_type
+ * @see get_object_taxonomies() for more on $object_type.
  *
- * @param int|array $object_ids Single or list of term object ID(s)
- * @param array|string $object_type The taxonomy object type
+ * @param int|array    $object_ids  Single or list of term object ID(s).
+ * @param array|string $object_type The taxonomy object type.
  */
 function clean_object_term_cache($object_ids, $object_type) {
 	if ( !is_array($object_ids) )
@@ -3728,13 +3806,20 @@ function clean_object_term_cache($object_ids, $object_type) {
  * @since 2.3.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
+ * @global bool $_wp_suspend_cache_invalidation
  *
- * @param int|array $ids Single or list of Term IDs
- * @param string $taxonomy Can be empty and will assume tt_ids, else will use for context.
- * @param bool $clean_taxonomy Whether to clean taxonomy wide caches (true), or just individual term object caches (false). Default is true.
+ * @param int|array $ids            Single or list of Term IDs.
+ * @param string    $taxonomy       Optional. Can be empty and will assume `tt_ids`, else will use for context.
+ *                                  Default empty.
+ * @param bool      $clean_taxonomy Optional. Whether to clean taxonomy wide caches (true), or just individual
+ *                                  term object caches (false). Default true.
  */
 function clean_term_cache($ids, $taxonomy = '', $clean_taxonomy = true) {
-	global $wpdb;
+	global $wpdb, $_wp_suspend_cache_invalidation;
+
+	if ( ! empty( $_wp_suspend_cache_invalidation ) ) {
+		return;
+	}
 
 	if ( !is_array($ids) )
 		$ids = array($ids);
@@ -3789,13 +3874,13 @@ function clean_term_cache($ids, $taxonomy = '', $clean_taxonomy = true) {
  *
  * @since 2.3.0
  *
- * @param int    $id       Term object ID
- * @param string $taxonomy Taxonomy Name
- * @return bool|array Empty array if $terms found, but not $taxonomy. False if nothing is in cache for $taxonomy and $id.
+ * @param int    $id       Term object ID.
+ * @param string $taxonomy Taxonomy name.
+ * @return bool|mixed Empty array if $terms found, but not `$taxonomy`. False if nothing is in cache
+ *                    for `$taxonomy` and `$id`.
  */
-function get_object_term_cache($id, $taxonomy) {
-	$cache = wp_cache_get($id, "{$taxonomy}_relationships");
-	return $cache;
+function get_object_term_cache( $id, $taxonomy ) {
+	return wp_cache_get( $id, "{$taxonomy}_relationships" );
 }
 
 /**
@@ -3810,10 +3895,9 @@ function get_object_term_cache($id, $taxonomy) {
  *
  * @since 2.3.0
  *
- * @param string|array $object_ids  Comma-separated list or array of term object IDs..
+ * @param string|array $object_ids  Comma-separated list or array of term object IDs.
  * @param array|string $object_type The taxonomy object type.
- * @return null|false Null if `$object_ids` is empty, false if all of the terms in
- *                    `$object_ids` are already cached.
+ * @return void|false False if all of the terms in `$object_ids` are already cached.
  */
 function update_object_term_cache($object_ids, $object_type) {
 	if ( empty($object_ids) )
@@ -3867,10 +3951,10 @@ function update_object_term_cache($object_ids, $object_type) {
  *
  * @since 2.3.0
  *
- * @param array $terms List of Term objects to change
- * @param string $taxonomy Optional. Update Term to this taxonomy in cache
+ * @param array  $terms    List of term objects to change.
+ * @param string $taxonomy Optional. Update Term to this taxonomy in cache. Default empty.
  */
-function update_term_cache($terms, $taxonomy = '') {
+function update_term_cache( $terms, $taxonomy = '' ) {
 	foreach ( (array) $terms as $term ) {
 		$term_taxonomy = $taxonomy;
 		if ( empty($term_taxonomy) )
@@ -3887,13 +3971,13 @@ function update_term_cache($terms, $taxonomy = '') {
 /**
  * Retrieves children of taxonomy as Term IDs.
  *
- * @access private
+ * @ignore
  * @since 2.3.0
  *
- * @param string $taxonomy Taxonomy Name
+ * @param string $taxonomy Taxonomy name.
  * @return array Empty if $taxonomy isn't hierarchical or returns children as Term IDs.
  */
-function _get_term_hierarchy($taxonomy) {
+function _get_term_hierarchy( $taxonomy ) {
 	if ( !is_taxonomy_hierarchical($taxonomy) )
 		return array();
 	$children = get_option("{$taxonomy}_children");
@@ -3914,20 +3998,21 @@ function _get_term_hierarchy($taxonomy) {
 /**
  * Get the subset of $terms that are descendants of $term_id.
  *
- * If $terms is an array of objects, then _get_term_children returns an array of objects.
- * If $terms is an array of IDs, then _get_term_children returns an array of IDs.
+ * If `$terms` is an array of objects, then _get_term_children() returns an array of objects.
+ * If `$terms` is an array of IDs, then _get_term_children() returns an array of IDs.
  *
  * @access private
  * @since 2.3.0
  *
- * @param int $term_id The ancestor term: all returned terms should be descendants of $term_id.
+ * @param int    $term_id   The ancestor term: all returned terms should be descendants of `$term_id`.
  * @param array  $terms     The set of terms - either an array of term objects or term IDs - from which those that
  *                          are descendants of $term_id will be chosen.
  * @param string $taxonomy  The taxonomy which determines the hierarchy of the terms.
- * @param array  $ancestors Term ancestors that have already been identified. Passed by reference, to keep track of
- *                          found terms when recursing the hierarchy. The array of located ancestors is used to prevent
- *                          infinite recursion loops. For performance, term_ids are used as array keys, with 1 as value.
- * @return array The subset of $terms that are descendants of $term_id.
+ * @param array  $ancestors Optional. Term ancestors that have already been identified. Passed by reference, to keep
+ *                          track of found terms when recursing the hierarchy. The array of located ancestors is used
+ *                          to prevent infinite recursion loops. For performance, `term_ids` are used as array keys,
+ *                          with 1 as value. Default empty array.
+ * @return array|WP_Error The subset of $terms that are descendants of $term_id.
  */
 function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array() ) {
 	$empty_array = array();
@@ -3989,11 +4074,10 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array()
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array $terms List of Term IDs
- * @param string $taxonomy Term Context
- * @return null Will break from function if conditions are not met.
+ * @param array  $terms    List of term IDs, passed by reference.
+ * @param string $taxonomy Term context.
  */
-function _pad_term_counts(&$terms, $taxonomy) {
+function _pad_term_counts( &$terms, $taxonomy ) {
 	global $wpdb;
 
 	// This function only works for hierarchical taxonomies like post categories.
@@ -4014,7 +4098,7 @@ function _pad_term_counts(&$terms, $taxonomy) {
 		$term_ids[$term->term_taxonomy_id] = $term->term_id;
 	}
 
-	// Get the object and term ids and stick them in a lookup table
+	// Get the object and term ids and stick them in a lookup table.
 	$tax_obj = get_taxonomy($taxonomy);
 	$object_types = esc_sql($tax_obj->object_type);
 	$results = $wpdb->get_results("SELECT object_id, term_taxonomy_id FROM $wpdb->term_relationships INNER JOIN $wpdb->posts ON object_id = ID WHERE term_taxonomy_id IN (" . implode(',', array_keys($term_ids)) . ") AND post_type IN ('" . implode("', '", $object_types) . "') AND post_status = 'publish'");
@@ -4023,7 +4107,7 @@ function _pad_term_counts(&$terms, $taxonomy) {
 		$term_items[$id][$row->object_id] = isset($term_items[$id][$row->object_id]) ? ++$term_items[$id][$row->object_id] : 1;
 	}
 
-	// Touch every ancestor's lookup row for each post in each term
+	// Touch every ancestor's lookup row for each post in each term.
 	foreach ( $term_ids as $term_id ) {
 		$child = $term_id;
 		$ancestors = array();
@@ -4041,7 +4125,7 @@ function _pad_term_counts(&$terms, $taxonomy) {
 		}
 	}
 
-	// Transfer the touched cells
+	// Transfer the touched cells.
 	foreach ( (array) $term_items as $id => $items )
 		if ( isset($terms_by_id[$id]) )
 			$terms_by_id[$id]->count = count($items);
@@ -4062,8 +4146,8 @@ function _pad_term_counts(&$terms, $taxonomy) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array $terms List of Term taxonomy IDs
- * @param object $taxonomy Current taxonomy object of terms
+ * @param array  $terms    List of Term taxonomy IDs.
+ * @param object $taxonomy Current taxonomy object of terms.
  */
 function _update_post_term_count( $terms, $taxonomy ) {
 	global $wpdb;
@@ -4086,7 +4170,7 @@ function _update_post_term_count( $terms, $taxonomy ) {
 	foreach ( (array) $terms as $term ) {
 		$count = 0;
 
-		// Attachments can be 'inherit' status, we need to base count off the parent's status if so
+		// Attachments can be 'inherit' status, we need to base count off the parent's status if so.
 		if ( $check_attachments )
 			$count += (int) $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_relationships, $wpdb->posts p1 WHERE p1.ID = $wpdb->term_relationships.object_id AND ( post_status = 'publish' OR ( post_status = 'inherit' AND post_parent > 0 AND ( SELECT post_status FROM $wpdb->posts WHERE ID = p1.post_parent ) = 'publish' ) ) AND post_type = 'attachment' AND term_taxonomy_id = %d", $term ) );
 
@@ -4105,14 +4189,14 @@ function _update_post_term_count( $terms, $taxonomy ) {
 /**
  * Will update term count based on number of objects.
  *
- * Default callback for the link_category taxonomy.
+ * Default callback for the 'link_category' taxonomy.
  *
  * @since 3.3.0
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array $terms List of Term taxonomy IDs
- * @param object $taxonomy Current taxonomy object of terms
+ * @param array  $terms    List of term taxonomy IDs.
+ * @param object $taxonomy Current taxonomy object of terms.
  */
 function _update_generic_term_count( $terms, $taxonomy ) {
 	global $wpdb;
@@ -4130,34 +4214,61 @@ function _update_generic_term_count( $terms, $taxonomy ) {
 }
 
 /**
- * Create a new term for a term_taxonomy item that currently shares its term with another term_taxonomy.
+ * Create a new term for a term_taxonomy item that currently shares its term
+ * with another term_taxonomy.
  *
  * @ignore
  * @since 4.2.0
- *
- * @param int  $term_id          ID of the shared term.
- * @param int  $term_taxonomy_id ID of the term_taxonomy item to receive a new term.
+ * @since 4.3.0 Introduced `$record` parameter. Also, `$term_id` and
+ *              `$term_taxonomy_id` can now accept objects.
+ *
+ * @global wpdb $wpdb
+ *
+ * @param int|object $term_id          ID of the shared term, or the shared term object.
+ * @param int|object $term_taxonomy_id ID of the term_taxonomy item to receive a new term, or the term_taxonomy object
+ *                                     (corresponding to a row from the term_taxonomy table).
+ * @param bool       $record           Whether to record data about the split term in the options table. The recording
+ *                                     process has the potential to be resource-intensive, so during batch operations
+ *                                     it can be beneficial to skip inline recording and do it just once, after the
+ *                                     batch is processed. Only set this to `false` if you know what you are doing.
+ *                                     Default: true.
  * @return int|WP_Error When the current term does not need to be split (or cannot be split on the current
  *                      database schema), `$term_id` is returned. When the term is successfully split, the
  *                      new term_id is returned. A WP_Error is returned for miscellaneous errors.
  */
-function _split_shared_term( $term_id, $term_taxonomy_id ) {
+function _split_shared_term( $term_id, $term_taxonomy_id, $record = true ) {
 	global $wpdb;
 
-	// Don't try to split terms if database schema does not support shared slugs.
-	$current_db_version = get_option( 'db_version' );
-	if ( $current_db_version < 30133 ) {
-		return $term_id;
+	if ( is_object( $term_id ) ) {
+		$shared_term = $term_id;
+		$term_id = intval( $shared_term->term_id );
+	}
+
+	if ( is_object( $term_taxonomy_id ) ) {
+		$term_taxonomy = $term_taxonomy_id;
+		$term_taxonomy_id = intval( $term_taxonomy->term_taxonomy_id );
 	}
 
 	// If there are no shared term_taxonomy rows, there's nothing to do here.
 	$shared_tt_count = $wpdb->get_var( $wpdb->prepare( "SELECT COUNT(*) FROM $wpdb->term_taxonomy tt WHERE tt.term_id = %d AND tt.term_taxonomy_id != %d", $term_id, $term_taxonomy_id ) );
+
 	if ( ! $shared_tt_count ) {
 		return $term_id;
 	}
 
+	/*
+	 * Verify that the term_taxonomy_id passed to the function is actually associated with the term_id.
+	 * If there's a mismatch, it may mean that the term is already split. Return the actual term_id from the db.
+	 */
+	$check_term_id = $wpdb->get_var( $wpdb->prepare( "SELECT term_id FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
+	if ( $check_term_id != $term_id ) {
+		return $check_term_id;
+	}
+
 	// Pull up data about the currently shared slug, which we'll use to populate the new one.
-	$shared_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.* FROM $wpdb->terms t WHERE t.term_id = %d", $term_id ) );
+	if ( empty( $shared_term ) ) {
+		$shared_term = $wpdb->get_row( $wpdb->prepare( "SELECT t.* FROM $wpdb->terms t WHERE t.term_id = %d", $term_id ) );
+	}
 
 	$new_term_data = array(
 		'name' => $shared_term->name,
@@ -4178,9 +4289,11 @@ function _split_shared_term( $term_id, $term_taxonomy_id ) {
 	);
 
 	// Reassign child terms to the new parent.
-	$term_taxonomy = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
-	$children_tt_ids = $wpdb->get_col( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_taxonomy WHERE taxonomy = %s AND parent = %d", $term_taxonomy->taxonomy, $term_id ) );
+	if ( empty( $term_taxonomy ) ) {
+		$term_taxonomy = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->term_taxonomy WHERE term_taxonomy_id = %d", $term_taxonomy_id ) );
+	}
 
+	$children_tt_ids = $wpdb->get_col( $wpdb->prepare( "SELECT term_taxonomy_id FROM $wpdb->term_taxonomy WHERE parent = %d AND taxonomy = %s", $term_id, $term_taxonomy->taxonomy ) );
 	if ( ! empty( $children_tt_ids ) ) {
 		foreach ( $children_tt_ids as $child_tt_id ) {
 			$wpdb->update( $wpdb->term_taxonomy,
@@ -4203,14 +4316,15 @@ function _split_shared_term( $term_id, $term_taxonomy_id ) {
 	}
 
 	// Keep a record of term_ids that have been split, keyed by old term_id. See {@see wp_get_split_term()}.
-	$split_term_data = get_option( '_split_terms', array() );
-	if ( ! isset( $split_term_data[ $term_id ] ) ) {
-		$split_term_data[ $term_id ] = array();
-	}
-
-	$split_term_data[ $term_id ][ $term_taxonomy->taxonomy ] = $new_term_id;
+	if ( $record ) {
+		$split_term_data = get_option( '_split_terms', array() );
+		if ( ! isset( $split_term_data[ $term_id ] ) ) {
+			$split_term_data[ $term_id ] = array();
+		}
 
-	update_option( '_split_terms', $split_term_data );
+		$split_term_data[ $term_id ][ $term_taxonomy->taxonomy ] = $new_term_id;
+		update_option( '_split_terms', $split_term_data );
+	}
 
 	/**
 	 * Fires after a previously shared taxonomy term is split into two separate terms.
@@ -4227,6 +4341,114 @@ function _split_shared_term( $term_id, $term_taxonomy_id ) {
 	return $new_term_id;
 }
 
+/**
+ * Splits a batch of shared taxonomy terms.
+ *
+ * @since 4.3.0
+ *
+ * @global wpdb $wpdb WordPress database abstraction object.
+ */
+function _wp_batch_split_terms() {
+	global $wpdb;
+
+	$lock_name = 'term_split.lock';
+
+	// Try to lock.
+	$lock_result = $wpdb->query( $wpdb->prepare( "INSERT IGNORE INTO `$wpdb->options` ( `option_name`, `option_value`, `autoload` ) VALUES (%s, %s, 'no') /* LOCK */", $lock_name, time() ) );
+
+	if ( ! $lock_result ) {
+		$lock_result = get_option( $lock_name );
+
+		// Bail if we were unable to create a lock, or if the existing lock is still valid.
+		if ( ! $lock_result || ( $lock_result > ( time() - HOUR_IN_SECONDS ) ) ) {
+			wp_schedule_single_event( time() + ( 5 * MINUTE_IN_SECONDS ), 'wp_split_shared_term_batch' );
+			return;
+		}
+	}
+
+	// Update the lock, as by this point we've definitely got a lock, just need to fire the actions.
+	update_option( $lock_name, time() );
+
+	// Get a list of shared terms (those with more than one associated row in term_taxonomy).
+	$shared_terms = $wpdb->get_results(
+		"SELECT tt.term_id, t.*, count(*) as term_tt_count FROM {$wpdb->term_taxonomy} tt
+		 LEFT JOIN {$wpdb->terms} t ON t.term_id = tt.term_id
+		 GROUP BY t.term_id
+		 HAVING term_tt_count > 1
+		 LIMIT 10"
+	);
+
+	// No more terms, we're done here.
+	if ( ! $shared_terms ) {
+		update_option( 'finished_splitting_shared_terms', true );
+		delete_option( $lock_name );
+		return;
+	}
+
+	// Shared terms found? We'll need to run this script again.
+	wp_schedule_single_event( time() + ( 2 * MINUTE_IN_SECONDS ), 'wp_split_shared_term_batch' );
+
+	// Rekey shared term array for faster lookups.
+	$_shared_terms = array();
+	foreach ( $shared_terms as $shared_term ) {
+		$term_id = intval( $shared_term->term_id );
+		$_shared_terms[ $term_id ] = $shared_term;
+	}
+	$shared_terms = $_shared_terms;
+
+	// Get term taxonomy data for all shared terms.
+	$shared_term_ids = implode( ',', array_keys( $shared_terms ) );
+	$shared_tts = $wpdb->get_results( "SELECT * FROM {$wpdb->term_taxonomy} WHERE `term_id` IN ({$shared_term_ids})" );
+
+	// Split term data recording is slow, so we do it just once, outside the loop.
+	$split_term_data = get_option( '_split_terms', array() );
+	$skipped_first_term = $taxonomies = array();
+	foreach ( $shared_tts as $shared_tt ) {
+		$term_id = intval( $shared_tt->term_id );
+
+		// Don't split the first tt belonging to a given term_id.
+		if ( ! isset( $skipped_first_term[ $term_id ] ) ) {
+			$skipped_first_term[ $term_id ] = 1;
+			continue;
+		}
+
+		if ( ! isset( $split_term_data[ $term_id ] ) ) {
+			$split_term_data[ $term_id ] = array();
+		}
+
+		// Keep track of taxonomies whose hierarchies need flushing.
+		if ( ! isset( $taxonomies[ $shared_tt->taxonomy ] ) ) {
+			$taxonomies[ $shared_tt->taxonomy ] = 1;
+		}
+
+		// Split the term.
+		$split_term_data[ $term_id ][ $shared_tt->taxonomy ] = _split_shared_term( $shared_terms[ $term_id ], $shared_tt, false );
+	}
+
+	// Rebuild the cached hierarchy for each affected taxonomy.
+	foreach ( array_keys( $taxonomies ) as $tax ) {
+		delete_option( "{$tax}_children" );
+		_get_term_hierarchy( $tax );
+	}
+
+	update_option( '_split_terms', $split_term_data );
+
+	delete_option( $lock_name );
+}
+
+/**
+ * In order to avoid the _wp_batch_split_terms() job being accidentally removed,
+ * check that it's still scheduled while we haven't finished splitting terms.
+ *
+ * @ignore
+ * @since 4.3.0
+ */
+function _wp_check_for_scheduled_split_terms() {
+	if ( ! get_option( 'finished_splitting_shared_terms' ) && ! wp_next_scheduled( 'wp_split_shared_term_batch' ) ) {
+		wp_schedule_single_event( time() + MINUTE_IN_SECONDS, 'wp_split_shared_term_batch' );
+	}
+}
+
 /**
  * Check default categories when a term gets split to see if any of them need to be updated.
  *
@@ -4256,6 +4478,8 @@ function _wp_check_split_default_terms( $term_id, $new_term_id, $term_taxonomy_i
  * @ignore
  * @since 4.2.0
  *
+ * @global wpdb $wpdb
+ *
  * @param int    $term_id          ID of the formerly shared term.
  * @param int    $new_term_id      ID of the new term created for the $term_taxonomy_id.
  * @param int    $term_taxonomy_id ID for the term_taxonomy row affected by the split.
@@ -4282,6 +4506,34 @@ function _wp_check_split_terms_in_menus( $term_id, $new_term_id, $term_taxonomy_
 	}
 }
 
+/**
+ * If the term being split is a nav_menu, change associations.
+ *
+ * @ignore
+ * @since 4.3.0
+ *
+ * @global wpdb $wpdb
+ *
+ * @param int    $term_id          ID of the formerly shared term.
+ * @param int    $new_term_id      ID of the new term created for the $term_taxonomy_id.
+ * @param int    $term_taxonomy_id ID for the term_taxonomy row affected by the split.
+ * @param string $taxonomy         Taxonomy for the split term.
+ */
+function _wp_check_split_nav_menu_terms( $term_id, $new_term_id, $term_taxonomy_id, $taxonomy ) {
+	if ( 'nav_menu' !== $taxonomy ) {
+		return;
+	}
+
+	// Update menu locations.
+	$locations = get_nav_menu_locations();
+	foreach ( $locations as $location => $menu_id ) {
+		if ( $term_id == $menu_id ) {
+			$locations[ $location ] = $new_term_id;
+		}
+	}
+	set_theme_mod( 'nav_menu_locations', $locations );
+}
+
 /**
  * Get data about terms that previously shared a single term_id, but have since been split.
  *
@@ -4308,9 +4560,9 @@ function wp_get_split_terms( $old_term_id ) {
  *
  * @param int    $old_term_id Term ID. This is the old, pre-split term ID.
  * @param string $taxonomy    Taxonomy that the term belongs to.
- * @return bool|int If a previously split term is found corresponding to the old term_id and taxonomy,
- *                  the new term_id will be returned. If no previously split term is found matching
- *                  the parameters, returns false.
+ * @return int|false If a previously split term is found corresponding to the old term_id and taxonomy,
+ *                   the new term_id will be returned. If no previously split term is found matching
+ *                   the parameters, returns false.
  */
 function wp_get_split_term( $old_term_id, $taxonomy ) {
 	$split_terms = wp_get_split_terms( $old_term_id );
@@ -4328,18 +4580,20 @@ function wp_get_split_term( $old_term_id, $taxonomy ) {
  *
  * @since 2.5.0
  *
+ * @global WP_Rewrite $wp_rewrite
+ *
  * @param object|int|string $term     The term object, ID, or slug whose link will be retrieved.
  * @param string            $taxonomy Optional. Taxonomy. Default empty.
  * @return string|WP_Error HTML link to taxonomy term archive on success, WP_Error if term does not exist.
  */
-function get_term_link( $term, $taxonomy = '') {
+function get_term_link( $term, $taxonomy = '' ) {
 	global $wp_rewrite;
 
 	if ( !is_object($term) ) {
-		if ( is_int($term) ) {
-			$term = get_term($term, $taxonomy);
+		if ( is_int( $term ) ) {
+			$term = get_term( $term, $taxonomy );
 		} else {
-			$term = get_term_by('slug', $term, $taxonomy);
+			$term = get_term_by( 'slug', $term, $taxonomy );
 		}
 	}
 
@@ -4429,8 +4683,8 @@ function get_term_link( $term, $taxonomy = '') {
  * @since 2.5.0
  *
  * @param array $args {
- *     Arguments about which post to use and how to format the output. Shares all of the arguments supported by
- *     {@link get_the_taxonomies()}, in addition to the following.
+ *     Arguments about which post to use and how to format the output. Shares all of the arguments
+ *     supported by get_the_taxonomies(), in addition to the following.
  *
  *     @type  int|WP_Post $post   Post ID or object to get taxonomies of. Default current post.
  *     @type  string      $before Displays before the taxonomies. Default empty string.
@@ -4462,7 +4716,7 @@ function the_taxonomies( $args = array() ) {
  *
  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
  * @param array $args {
- *     Arguments about how to format the list of taxonomies.
+ *     Optional. Arguments about how to format the list of taxonomies. Default empty array.
  *
  *     @type string $template      Template for displaying a taxonomy label and list of terms.
  *                                 Default is "Label: Terms."
@@ -4540,9 +4794,9 @@ function get_post_taxonomies( $post = 0 ) {
  *
  * @since 2.7.0
  *
- * @param int $object_id ID of the object (post ID, link ID, ...)
- * @param string $taxonomy Single taxonomy name
- * @param int|string|array $terms Optional. Term term_id, name, slug or array of said
+ * @param int              $object_id ID of the object (post ID, link ID, ...).
+ * @param string           $taxonomy  Single taxonomy name.
+ * @param int|string|array $terms     Optional. Term term_id, name, slug or array of said. Default null.
  * @return bool|WP_Error WP_Error on input error.
  */
 function is_object_in_term( $object_id, $taxonomy, $terms = null ) {
@@ -4593,20 +4847,16 @@ function is_object_in_term( $object_id, $taxonomy, $terms = null ) {
  *
  * @since 3.0.0
  *
- * @param string $object_type Object type string
- * @param string $taxonomy Single taxonomy name
+ * @param string $object_type Object type string.
+ * @param string $taxonomy    Single taxonomy name.
  * @return bool True if object is associated with the taxonomy, otherwise false.
  */
-function is_object_in_taxonomy($object_type, $taxonomy) {
-	$taxonomies = get_object_taxonomies($object_type);
-
-	if ( empty($taxonomies) )
+function is_object_in_taxonomy( $object_type, $taxonomy ) {
+	$taxonomies = get_object_taxonomies( $object_type );
+	if ( empty( $taxonomies ) ) {
 		return false;
-
-	if ( in_array($taxonomy, $taxonomies) )
-		return true;
-
-	return false;
+	}
+	return in_array( $taxonomy, $taxonomies );
 }
 
 /**
@@ -4655,7 +4905,7 @@ function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' )
 	 * Filter a given object's ancestors.
 	 *
 	 * @since 3.1.0
-	 * @since 4.1.0 Introduced the `$resource_type` parameter.
+	 * @since 4.1.1 Introduced the `$resource_type` parameter.
 	 *
 	 * @param array  $ancestors     An array of object ancestors.
 	 * @param int    $object_id     Object ID.
@@ -4666,19 +4916,19 @@ function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' )
 }
 
 /**
- * Returns the term's parent's term_ID
+ * Returns the term's parent's term_ID.
  *
  * @since 3.1.0
  *
- * @param int $term_id
- * @param string $taxonomy
- *
- * @return int|bool false on error
+ * @param int    $term_id  Term ID.
+ * @param string $taxonomy Taxonomy name.
+ * @return int|false False on error.
  */
 function wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) {
 	$term = get_term( $term_id, $taxonomy );
-	if ( !$term || is_wp_error( $term ) )
+	if ( ! $term || is_wp_error( $term ) ) {
 		return false;
+	}
 	return (int) $term->parent;
 }
 
@@ -4686,12 +4936,12 @@ function wp_get_term_taxonomy_parent_id( $term_id, $taxonomy ) {
  * Checks the given subset of the term hierarchy for hierarchy loops.
  * Prevents loops from forming and breaks those that it finds.
  *
- * Attached to the wp_update_term_parent filter.
+ * Attached to the {@see 'wp_update_term_parent'} filter.
  *
  * @since 3.1.0
  *
- * @param int $parent term_id of the parent for the term we're checking.
- * @param int $term_id The term we're checking.
+ * @param int    $parent   `term_id` of the parent for the term we're checking.
+ * @param int    $term_id  The term we're checking.
  * @param string $taxonomy The taxonomy of the term we're checking.
  *
  * @return int The new parent for the term.
@@ -4701,16 +4951,15 @@ function wp_check_term_hierarchy_for_loops( $parent, $term_id, $taxonomy ) {
 	if ( !$parent )
 		return 0;
 
-	// Can't be its own parent
+	// Can't be its own parent.
 	if ( $parent == $term_id )
 		return 0;
 
-	// Now look for larger loops
-
+	// Now look for larger loops.
 	if ( !$loop = wp_find_hierarchy_loop( 'wp_get_term_taxonomy_parent_id', $term_id, $parent, array( $taxonomy ) ) )
 		return $parent; // No loop
 
-	// Setting $parent to the given value causes a loop
+	// Setting $parent to the given value causes a loop.
 	if ( isset( $loop[$term_id] ) )
 		return 0;