[wp-trac] [WordPress Trac] #33014: Inline documentation for wp_transition_post_status is unclear as to what it actually does.

[WordPress Trac]

#33014: Inline documentation for wp_transition_post_status is unclear as to what it
actually does.
--------------------------+-----------------------------
 Reporter:  AramZS        |      Owner:
     Type:  defect (bug)  |     Status:  new
 Priority:  normal        |  Milestone:  Awaiting Review
Component:  General       |    Version:  trunk
 Severity:  normal        |   Keywords:
  Focuses:  docs          |
--------------------------+-----------------------------
 It appears from both the name and the in-line documentation of
 wp_transition_post_status that calling that function with two statuses and
 a post object would transition the status of the post object.

 This is not the case.

 `wp_transition_post_status` is a function called during the process of
 transitioning a post_status, not the process itself, and is just a method
 to fire off a series of hooks. The documentation should reflect that for
 users who might encounter the function through Code Reference and not see
 the actual content of the function, only the documentation.

 As a note for the future, it might make sense to indicate this as an
 internals-only function, or give it a name more consistent with what it
 does. That said, the purpose of this ticket is to merely update the docs.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/33014>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform