Clarify the docs and add more unit tests for wp_set_object_terms().

props DrewAPicture.
fixes #26570.
Built from https://develop.svn.wordpress.org/trunk@28951


git-svn-id: http://core.svn.wordpress.org/trunk@28748 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/taxonomy.php

@@ -2618,11 +2618,11 @@ function wp_insert_term( $term, $taxonomy, $args = array() ) {
  * @uses wp_remove_object_terms()
  *
  * @param int              $object_id The object to relate to.
- * @param array|int|string $terms The slug or id of the term, will replace all existing
- * related terms in this taxonomy.
+ * @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.
  * @param array|string     $taxonomy  The context in which to relate the term to the object.
  * @param bool             $append    If false will delete difference of terms.
- * @return array|WP_Error Affected Term IDs
+ * @return array|WP_Error Affected Term IDs.
  */
 function wp_set_object_terms( $object_id, $terms, $taxonomy, $append = false ) {
 	global $wpdb;