Make WordPress Core

#57047 closed defect (bug) (fixed)

Misleading PHPdoc for filter {$adjacent}_post_link

Reported by: apermo's profile apermo Owned by: sergeybiryukov's profile SergeyBiryukov
Milestone: 6.2 Priority: normal
Severity: normal Version: 4.2
Component: Posts, Post Types Keywords: has-patch
Focuses: docs Cc:

Description

The documentation for the filter {$adjacent}_post_link inside /wp-includes/link-template.php suggests that $post is a WP_Post.
The function get_adjacent_post() though will deliver an empty string if there is no adjacent post.

It is arguable if get_adjacent_post() shouldn't return null in that case, but nevertheless, in it's current state, the PHPdoc for the filter is misleading. If one uses these for typehinting, a fatal error will be thrown.

I've attached a patch, with my suggestion for an updated PHPdoc.

Attachments (1)

link-template.patch (1.2 KB) - added by apermo 21 months ago.
Patch of the PHPdoc.

Download all attachments as: .zip

Change History (5)

@apermo
21 months ago

Patch of the PHPdoc.

#1 @audrasjb
21 months ago

  • Keywords has-patch added
  • Version changed from 6.1 to 4.2

Hello, thanks for the ticket and for the related patch,

Maybe we could use a similar wording than the one used in the get_adjacent_post() function?
Empty string if no corresponding post exists.

Updating the Version tag to 4.2 as this filter was added in this version.

#2 @apermo
21 months ago

I'm fine with any wording, as long, as the type is updated to WP_Post|string.

And thanks for the quick response.

#3 @SergeyBiryukov
20 months ago

  • Focuses docs added
  • Milestone changed from Awaiting Review to 6.2

#4 @SergeyBiryukov
20 months ago

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

In 54841:

Docs: Correct type for the $post parameter of the {$adjacent}_post_link filter.

The parameter was documented as WP_Post, but it contains the value of get_adjacent_post(), which returns an empty string if there is no corresponding post, so the correct type is WP_Post|string.

Follow-up to [11243], [16951], [28111], [32606].

Props apermo, audrasjb.
Fixes #57047.

Note: See TracTickets for help on using tickets.