WordPress.org

Make WordPress Core

Opened 4 months ago

Closed 4 months ago

Last modified 4 months ago

#48397 closed defect (bug) (fixed)

PHPDoc correction for wptexturize() in wp-includes/formatting.php

Reported by: atachibana Owned by: SergeyBiryukov
Milestone: 5.4 Priority: normal
Severity: minor Version:
Component: Formatting Keywords: has-patch
Focuses: docs Cc:

Description

Enhanced missing information of Codex for add_help_tab() in wp-admin/includes/class-wp-screen.php:

  • Function description
  • since 4.0 information

Other missing information in Notes section were added to Code Reference as 'More Information'.

Codex: https://codex.wordpress.org/Function_Reference/wptexturize
Code Reference: https://developer.wordpress.org/reference/functions/wptexturize/

This is the action of inline docs and Codex migration initiatives.

Index: formatting.php
===================================================================
--- formatting.php	(revision 46568)
+++ formatting.php	(working copy)
@@ -10,6 +10,8 @@
 /**
  * Replaces common plain text characters into formatted entities
  *
+ * This returns given text with transformations of quotes to smart quotes,
+ * apostrophes, dashes, ellipses, the trademark symbol, and the multiplication symbol.
  * As an example,
  *
  *     'cause today's effort makes it worth tomorrow's "holiday" ...
@@ -23,6 +25,7 @@
  * Do not use this function before the {@see 'init'} action hook; everything will break.
  *
  * @since 0.71
+ * @since 4.0  Revised to improve performance and to resolve many bugs. Added the run_wptexturize filter to allow a theme or plugin to permanently disable this feature.
  *
  * @global array $wp_cockneyreplace Array of formatted entities for certain common phrases
  * @global array $shortcode_tags

Attachments (1)

48397.diff (938 bytes) - added by atachibana 4 months ago.

Download all attachments as: .zip

Change History (8)

@atachibana
4 months ago

#1 @atachibana
4 months ago

  • Keywords has-patch added

#2 follow-up: @johnbillion
4 months ago

@atachibana Thanks for the tickets! For each major release of WordPress we use a single tracking ticket for small inline documentation fixes such as this, so as to avoid a large number of documentation-only tickets on Trac. For 5.4 it's ticket #48303. Feel free to leave your comments on that ticket for any further improvements you identify.

#3 @SergeyBiryukov
4 months ago

  • Component changed from General to Formatting
  • Milestone changed from Awaiting Review to 5.4
  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

#4 in reply to: ↑ 2 @SergeyBiryukov
4 months ago

Replying to johnbillion:

For each major release of WordPress we use a single tracking ticket for small inline documentation fixes such as this, so as to avoid a large number of documentation-only tickets on Trac. For 5.4 it's ticket #48303.

FWIW, I find it easier to handle well-contained tickets like this separately than reviewing a lot of different changes on a single ticket, but yeah, either way should work.

#5 @SergeyBiryukov
4 months ago

Thanks for the patch!

Just noting that, per the documentation standards, @since tags are generally added for significant changes like:

  • Adding new arguments or parameters
  • Required arguments becoming optional
  • Changing default/expected behaviors
  • Functions or methods becoming wrappers for new APIs

Of the two sentences added here, neither quite seem to fit:

  • Revised to improve performance and to resolve many bugs.
  • Added the run_wptexturize filter to allow a theme or plugin to permanently disable this feature.

The former is an internal implementation detail that does not change the function signature and does not provide any information on the behavior changes, the latter seems redundant and just duplicates the existing filter documentation. New filters or actions generally have their own documentation and are not added to @since tags.

#6 @SergeyBiryukov
4 months ago

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

In 46592:

Docs: Improve documentation for wptexturize().

Props atachibana.
Fixes #48397.

#7 @atachibana
4 months ago

@johnbillion
I didn't know about the #48303.
I modified the inline documentation guide of Docs Team Handbook to follow your instruction.
https://make.wordpress.org/docs/handbook/code-reference/inline-documentation/

@SergeyBiryukov
Thank you for your always kindly guides.
I'll continue to include as much as details of the bug report even in the Comment area.

Note: See TracTickets for help on using tickets.