[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
noreply at wordpress.org
Tue Aug 20 11:42:51 UTC 2013
#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
More information about the wp-trac
mailing list