[wp-trac] [WordPress Trac] #38310: Improve "wp_update_term" documentation

[WordPress Trac]

#38310: Improve "wp_update_term" documentation
-------------------------------------------------+-------------------------
 Reporter:  ruud@…                               |       Owner:
     Type:  enhancement                          |      Status:  new
 Priority:  normal                               |   Milestone:  Future
Component:  Taxonomy                             |  Release
 Severity:  normal                               |     Version:  trunk
 Keywords:  good-first-bug has-patch dev-        |  Resolution:
  feedback needs-testing                         |     Focuses:  docs
-------------------------------------------------+-------------------------

Comment (by ruud@…):

 Hi @boonebgorges,

 Thanks for your reply.

 >From what I can see, passing term_id as part of the $args array will
 *already* be ignored. The only $args values that do anything are: 'name',
 'description', 'parent', 'term_group'.

 I think your mostly right, except that the entire $args array is also
 passed to wp_unique_term_slug on line 2908:
 $slug = wp_unique_term_slug($slug, (object) $args);

 None of the other $args values are filtered out and 'survive' the entire
 function to this point and further along.

 >The "Care must be taken..." line is another one that doesn't make much
 sense for modern WordPress.
 Indeed.

 >We use $args from a whitelist. It's not possible to modify existing terms
 in way other than these whitelisted arguments.

 Not entirely true, I think it is possible to alter the slug via a slug
 from another term (via a different term_id via $args), see remark about
 the wp_unique_term_slug() function in use.

 >Maybe what's meant is: if you don't want to change the 'description'
 field, don't pass a 'description' key, etc. If so, this could use some
 rewording.

 Indeed, I'm not a big fan of mentioning things in the docs which
 might/could happen if used in some way etc. Stating what a function does
 do, seems a much more prudent way. Adding some more clarification in the
 @params could help?

 I'm curious if I'm missing the obvious here with the possibility of mis-
 using a 'term_id' in $args here.

 Thanks
 Ruud

--
Ticket URL: <https://core.trac.wordpress.org/ticket/38310#comment:7>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform