Inline documentation for wp_transition_post_status is unclear as to what it actually does.

[AramZS]

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.

[AramZS]

Patch to update the documentation of wp_transition_post_status to make it clearer what the function actually does.

[AramZS]

First time I've done an actual patch and I'm not used to SVN, so please excuse any potential error there.

[boonebgorges]

Thanks for the patch, AramZS!

[kraftbj]

Thanks to the patch! As for SVN best practice, it's best to create the patch from the SVN root so it picks up the full path. With post.php.patch, it isn't clear what "post.php" file we're needing to patch.

If svn diff > ../33014.patch from the svn root, it'll pick up the full src/wp-admin/includes/whatever-the-path/post.php. It's helpful to reduce confusion and those that use the grunt patch:33014 method to apply patches.

Thanks again! I'll defer to the Docs maintainers for commenting on the patch itself. Without verifying the report, it sounds like an useful clarification.

[boonebgorges]

In 33296:

Improve function description for wp_transition_post_status().

The documentation should make it clear that the function does not modify the
post object in the database, but only fires hooks related to the transition.

Props AramZS.
Fixes #33014.

[AramZS]

Replying to kraftbj:

Thanks to the patch! As for SVN best practice, it's best to create the patch from the SVN root so it picks up the full path. With post.php.patch, it isn't clear what "post.php" file we're needing to patch.

If svn diff > ../33014.patch from the svn root, it'll pick up the full src/wp-admin/includes/whatever-the-path/post.php. It's helpful to reduce confusion and those that use the grunt patch:33014 method to apply patches.

Thanks again! I'll defer to the Docs maintainers for commenting on the patch itself. Without verifying the report, it sounds like an useful clarification.

Ok, thank you, that's good to know so I can do it next time. I'll have to record the difference in my process so I can suggest a fix to the Make book for this process, I think there might be a setting missing there for how to do it with TortoiseSVN.