WordPress.org

Make WordPress Core

Opened 5 years ago

Closed 5 years ago

Last modified 5 years ago

#33014 closed defect (bug) (fixed)

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

Reported by: AramZS Owned by: boonebgorges
Milestone: 4.3 Priority: normal
Severity: normal Version: 4.3
Component: Posts, Post Types Keywords: has-patch
Focuses: docs Cc:
PR Number:

Description

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.

Attachments (1)

post.php.patch (1.0 KB) - added by AramZS 5 years ago.
Patch to update the documentation of wp_transition_post_status to make it clearer what the function actually does.

Download all attachments as: .zip

Change History (6)

@AramZS
5 years ago

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

#1 @AramZS
5 years ago

  • Keywords has-patch added

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

#2 @boonebgorges
5 years ago

  • Component changed from General to Posts, Post Types
  • Milestone changed from Awaiting Review to 4.3

Thanks for the patch, AramZS!

#3 follow-up: @kraftbj
5 years ago

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.

#4 @boonebgorges
5 years ago

  • Owner set to boonebgorges
  • Resolution set to fixed
  • Status changed from new to closed

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.

#5 in reply to: ↑ 3 @AramZS
5 years ago

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.

Note: See TracTickets for help on using tickets.