WordPress 4.3.1
[autoinstalls/wordpress.git] / wp-includes / taxonomy.php
index cce486786b3f96030dee795bd112a72f762d02f4..4328a366707338df6759ca701085773158ded9e7 100644 (file)
@@ -2,9 +2,10 @@
 /**
  * Taxonomy API
  *
+ * @since 2.3.0
+ *
  * @package WordPress
  * @subpackage Taxonomy
- * @since 2.3.0
  */
 
 //
  * 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.
- * @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();
@@ -3942,7 +4027,7 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array()
 
        // Include the term itself in the ancestors array, so we can properly detect when a loop has occurred.
        if ( empty( $ancestors ) ) {
-               $ancestors[] = $term_id;
+               $ancestors[ $term_id ] = 1;
        }
 
        foreach ( (array) $terms as $term ) {
@@ -3955,7 +4040,7 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array()
                }
 
                // Don't recurse if we've already identified the term as a child - this indicates a loop.
-               if ( in_array( $term->term_id, $ancestors ) ) {
+               if ( isset( $ancestors[ $term->term_id ] ) ) {
                        continue;
                }
 
@@ -3968,11 +4053,7 @@ function _get_term_children( $term_id, $terms, $taxonomy, &$ancestors = array()
                        if ( !isset($has_children[$term->term_id]) )
                                continue;
 
-                       if ( $use_id ) {
-                               $ancestors = array_merge( $ancestors, $term_list );
-                       } else {
-                               $ancestors = array_merge( $ancestors, wp_list_pluck( $term_list, 'term_id' ) );
-                       }
+                       $ancestors[ $term->term_id ] = 1;
 
                        if ( $children = _get_term_children( $term->term_id, $terms, $taxonomy, $ancestors) )
                                $term_list = array_merge($term_list, $children);
@@ -3993,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.
@@ -4018,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'");
@@ -4027,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();
@@ -4045,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);
@@ -4066,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;
@@ -4090,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 ) );
 
@@ -4109,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;
@@ -4134,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,
@@ -4182,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,
@@ -4207,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.
@@ -4231,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.
  *
@@ -4260,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.
@@ -4286,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.
  *
@@ -4312,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 );
@@ -4332,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 );
                }
        }
 
@@ -4433,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.
@@ -4466,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."
@@ -4544,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 ) {
@@ -4597,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 );
 }
 
 /**
@@ -4659,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.
@@ -4670,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;
 }
 
@@ -4690,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.
@@ -4705,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;