Update documentation on wp_insert_term to state that it will return an error if inserting an existing term.

[lgedeon]

phpdoc for wp_insert_term() states:

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.

However it returns an error object instead. That may have changed with #13481. Anyway, returning an error seems to be an acceptable solution. Although, #16567 might change that a bit.

Should we just adjust the docs to fit the current behavior?

[c3mdigital]

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
 */

[DrewAPicture]

docblock redo

[DrewAPicture]

22801.diff​ rewrites big parts of this docblock for clarity, including the change about returning a WP_Error object mentioned in the ticket description.

Side note: this whole file is slated for a docs review anyway.

[DrewAPicture]

tense, wrapping

[SergeyBiryukov]

In 25489:

Update inline documentation for wp_insert_term().

props DrewAPicture.
fixes #22801.

[lgedeon]

Alternate list of of error triggers, and tense fix typo fix

[lgedeon]

Tried to follow the order of error triggers in the code, and also fixed a typo.

[SergeyBiryukov]

Looks like I used 22801.diff​ in [25489] instead of 22801.2.diff​.

22801.4.diff​ is a partial refresh of 22801.2.diff​ and 22801.3.diff​ against trunk, and is my take on further clarifying the error handling.

• A numeric $term is allowed, as long as it's not empty.
• A non-unique slug is also allowed (it will be regenerated), as long as the name is different.

[DrewAPicture]

In 25498:

Clarify error handling and special cases in the wp_insert_term() phpdoc block.

props lgedeon, SergeyBiryukov. See #22801.