From 8d2764fbd39b709f779eaa001355d41f3c3d9185 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Thu, 19 Sep 2013 01:57:10 +0000 Subject: [PATCH] Update inline documentation for wp_insert_term(). props DrewAPicture. fixes #22801. Built from https://develop.svn.wordpress.org/trunk@25489 git-svn-id: http://core.svn.wordpress.org/trunk@25410 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/taxonomy.php | 78 ++++++++++++++++++---------------------- 1 file changed, 34 insertions(+), 44 deletions(-) diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 676f059cf0..52f6c865d1 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -2020,57 +2020,47 @@ function wp_get_object_terms($object_ids, $taxonomies, $args = array()) { } /** - * Adds a new term to the database. Optionally marks it as an alias of an existing term. + * Add a new term to the database. * - * Error handling is assigned for the nonexistence of the $taxonomy and $term - * parameters before inserting. If both the term id and taxonomy exist - * previously, then an array will be returned that contains the term id and the - * contents of what is returned. The keys of the array are 'term_id' and - * 'term_taxonomy_id' containing numeric values. + * A non-existent term is inserted in the following sequence: + * 1. The term is added to the term table, then related to the taxonomy. + * 2. If everything is correct, several actions are fired. + * 3. The 'term_id_filter' is evaluated. + * 4. The term cache is cleaned. + * 5. Several more actions are fired. + * 6. An array is returned containing the term_id and term_taxonomy_id. * - * It is assumed that the term does not yet exist or the above will apply. The - * term will be first added to the term table and then related to the taxonomy - * if everything is well. If everything is correct, then several actions will be - * run prior to a filter and then several actions will be run after the filter - * is run. + * If the 'slug' argument is not empty, then it will be checked to see if the term + * is invalid. If it is not a valid, existing term, it is added and the term_id is given. + * If the taxonomy is hierarchical, and the 'parent' argument is not empty, the term + * will be inserted and the term_id will be given. + + * Error handling: + * If $taxonomy does not exist -- or $term is numeric or empty, + * a WP_Error object will be returned. * - * The arguments decide how the term is handled based on the $args parameter. - * The following is a list of the available overrides and the defaults. + * If the term already exists, the term slug is not unique, or both the term id and taxonomy + * already exist, a WP_Error object will be returned. * - * 'alias_of'. There is no default, but if added, expected is the slug that the - * term will be an alias of. Expected to be a string. - * - * 'description'. There is no default. If exists, will be added to the database - * along with the term. Expected to be a string. - * - * 'parent'. Expected to be numeric and default is 0 (zero). Will assign value - * of 'parent' to the term. - * - * 'slug'. Expected to be a string. There is no default. - * - * If 'slug' argument exists then the slug will be checked to see if it is not - * a valid term. If that check succeeds (it is not a valid term), then it is - * added and the term id is given. If it fails, then a check is made to whether - * the taxonomy is hierarchical and the parent argument is not empty. If the - * second check succeeds, the term will be inserted and the term id will be - * given. - * - * @package WordPress - * @subpackage Taxonomy + * @global wpdb $wpdb The WordPress database object. + * @since 2.3.0 - * @uses $wpdb * - * @uses apply_filters() Calls 'pre_insert_term' hook with term and taxonomy as parameters. - * @uses do_action() Calls 'create_term' hook with the term id and taxonomy id as parameters. - * @uses do_action() Calls 'create_$taxonomy' hook with term id and taxonomy id as parameters. - * @uses apply_filters() Calls 'term_id_filter' hook with term id and taxonomy id as parameters. - * @uses do_action() Calls 'created_term' hook with the term id and taxonomy id as parameters. - * @uses do_action() Calls 'created_$taxonomy' hook with term id and taxonomy id as parameters. + * @param string $term The term to add or update. + * @param string $taxonomy The taxonomy to which to add the term + * @param array|string $args { + * Arguments to change values of the inserted term. * - * @param string $term The term to add or update. - * @param string $taxonomy The taxonomy to which to add the term - * @param array|string $args Change the values of the inserted term - * @return array|WP_Error The Term ID and Term Taxonomy ID + * @type string 'alias_of' Slug of the term to make this term an alias of. + * Default empty string. Accepts a term slug. + * @type string 'description' The term description. + * Default empty string. + * @type int 'parent' The id of the parent term. + * Default 0. + * @type string 'slug' The term slug to use. + * Default empty string. + * } + * @return array|WP_Error An array containing the term_id and term_taxonomy_id, WP_Error otherwise. */ function wp_insert_term( $term, $taxonomy, $args = array() ) { global $wpdb;