WordPress.org

Make WordPress Core

Opened 3 years ago

Closed 2 years ago

Last modified 2 years ago

#45204 closed defect (bug) (fixed)

Fix a broken link for esc_like() in the wpdb->prepare() DocBlock

Reported by: DrewAPicture Owned by: antaltettinger
Milestone: 5.1 Priority: normal
Severity: normal Version:
Component: Database Keywords: good-first-bug has-patch commit
Focuses: docs Cc:

Description (last modified by DrewAPicture)

As reported by @timhavinga, the esc_like() reference in the fourth paragraph of the DocBlock description for wpdb->prepare() is invalid. It should point to to the wpdb->esc_like() method, vs a (nonexistent) standalone function.

The DocBlock description for a function, class, method, or hook corresponds to the Description section of the reference article for that element when it's parsed from source. So to reference a class method in a DocBlock with an inline @see tag, the format is {@see Class_Name::method_name()}

Current docs:

<?php
 * ...
 *
 * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards (for example,
 * to use in LIKE syntax) must be passed via a substitution argument containing the complete LIKE string, these
 * cannot be inserted directly in the query string. Also see {@see esc_like()}.
 *
 * ...
 */
public function prepare( $query, $args ) {
...

Attachments (2)

45204.diff (801 bytes) - added by antaltettinger 3 years ago.
Corrected with link to the requested Description section in the WordPress Codex
45204.2.diff (755 bytes) - added by antaltettinger 3 years ago.
Corrected to include text with the requested format.

Download all attachments as: .zip

Change History (9)

#1 @DrewAPicture
3 years ago

  • Description modified (diff)

Note: I've manually fixed the link in the Code Reference on a temporary basis pending a fix against the 5.1 milestone once trunk development reopens.

Last edited 3 years ago by DrewAPicture (previous) (diff)

#2 @DrewAPicture
3 years ago

  • Milestone changed from Awaiting Review to Future Release

@antaltettinger
3 years ago

Corrected with link to the requested Description section in the WordPress Codex

#3 @DrewAPicture
3 years ago

  • Keywords has-patch added
  • Owner set to antaltettinger
  • Status changed from new to assigned

Hi @antaltettinger, thanks for the patch. Unfortunately, it's not quite the fix we need.

Based on the second paragraph of the ticket description, all we really need to do is update the inline @see tag to match the {@see Class_Name::method_name()} syntax.

---

Assigning to mark the good-first-bug ticket as "claimed".

@antaltettinger
3 years ago

Corrected to include text with the requested format.

#4 @antaltettinger
3 years ago

Hi @DrewAPicture! Thank you very much for your quick reply. I have modified and uploaded the (hopefully) correct file. Thanks for the support, it's my first time to contribute on Track so it's testing waters for me.

#5 @DrewAPicture
3 years ago

  • Keywords commit added
  • Milestone changed from Future Release to 5.1

Hi @antaltettinger, that's exactly what I was looking for. Looks great!

Trunk development is still closed, but we'll get this one merged, probably as part of the 5.1 release when that opens back up again.

Thanks for the patch!

#6 @DrewAPicture
2 years ago

  • Resolution set to fixed
  • Status changed from assigned to closed

In 44330:

Docs: Update an inline @see reference in the DocBlock for wpdb::prepare() to reference wpdb::esc_like() the method instead of esc_like() the nonexistent function.

Props antaltettinger.
Fixes #45204.

#7 @SergeyBiryukov
2 years ago

In 44901:

Docs: Remove unnecessary @see tag in wpdb::prepare().

The tag is only necessary for hooks. For functions and methods, autolinking is handled automatically on developer.wordpress.org.

Props mbelchev, ocean90, johannadevos.
Fixes #44585. See #45204.

Note: See TracTickets for help on using tickets.