[wp-trac] [WordPress Trac] #22801: Update documentation on wp_insert_term to state that it will return an error if inserting an existing term.

[WordPress Trac]

#22801: Update documentation on wp_insert_term to state that it will return an
error if inserting an existing term.
--------------------------+------------------------------
 Reporter:  lgedeon       |       Owner:
     Type:  defect (bug)  |      Status:  new
 Priority:  normal        |   Milestone:  Awaiting Review
Component:  Inline Docs   |     Version:  2.3
 Severity:  normal        |  Resolution:
 Keywords:  needs-patch   |
--------------------------+------------------------------
Changes (by c3mdigital):

 * keywords:   => needs-patch
 * version:   => 2.3


Comment:

 Inline docs need to better explain the error handling.  Function returns
 WP_Error object.

 '''Current Inline doc:'''

 {{{
 /**
  * Adds a new term to the database. Optionally marks it as an alias of an
 existing term.
  *
  * 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.
  *
  * 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.
  *
  * 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.
  *
  * '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
  * @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 Change the values of the inserted term
  * @return array|WP_Error The Term ID and Term Taxonomy ID
  */
 }}}

--
Ticket URL: <http://core.trac.wordpress.org/ticket/22801#comment:1>
WordPress Trac <http://core.trac.wordpress.org/>
WordPress blogging software