WordPress.org

Make WordPress Core

Opened 7 weeks ago

Closed 6 weeks ago

#48383 closed defect (bug) (fixed)

PHPDoc correction for l10n functions (esc_attr_e, esc_html_e, esc_attr_x and esc_html_x) in wp-includes/l10n.php

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

Description (last modified by SergeyBiryukov)

Enhanced missing information of Codex for esc_attr_e, esc_attr_x, esc_html_e and esc_html_x in wp-includes/l10n.php. Other l10n functions are fully migrated.

$ svn diff l10n.php
Index: l10n.php
===================================================================
--- l10n.php	(revision 46561)
+++ l10n.php	(working copy)

// esc_attr_e()
// Codex: https://codex.wordpress.org/Function_Reference/esc_attr_e
// Code Reference: https://developer.wordpress.org/reference/functions/esc_attr_e/

@@ -304,6 +304,10 @@
 /**
  * Display translated text that has been escaped for safe use in an attribute.
  *
+ * Encodes < > & " ' (less than, greater than, ampersand, double quote, single quote).
+ * Will never double encode entities.
+ * If you need the value for use in PHP, use esc_attr__().
+ *
  * @since 2.8.0
  *
  * @param string $text   Text to translate.


// esc_html_e()
// Codex: https://codex.wordpress.org/Function_Reference/esc_html_e
// Code Reference: https://developer.wordpress.org/reference/functions/esc_html_e/

@@ -317,6 +321,9 @@
 /**
  * Display translated text that has been escaped for safe use in HTML output.
  *
+ * If there is no translation or the domain isn't loaded, the escaped original text is shown.
+ * If you need the value for use in PHP, use esc_html__().
+ *
  * @since 2.8.0
  *
  * @param string $text   Text to translate.


// esc_attr_x()
// Codex: https://codex.wordpress.org/Function_Reference/esc_attr_x
// Code Reference: https://developer.wordpress.org/reference/functions/esc_attr_x/

@@ -366,6 +373,8 @@
 /**
  * Translate string with gettext context, and escapes it for safe use in an attribute.
  *
+ * If there is no translation or the domain isn't loaded, the escaped original text is returned.
+ *
  * @since 2.8.0
  *
  * @param string $text    Text to translate.


// esc_html_x()
// Codex: https://codex.wordpress.org/Function_Reference/esc_html_x
// Code Reference: https://developer.wordpress.org/reference/functions/esc_html_x/

@@ -381,6 +390,8 @@
 /**
  * Translate string with gettext context, and escapes it for safe use in HTML output.
  *
+ * If there is no translation, or the domain isn't loaded, the escaped original text is returned.
+ *
  * @since 2.9.0
  *
  * @param string $text    Text to translate.

Other l10n functions are OK, fully migrated: translate(), __(), _e(), _n(), _x(), _ex(), _nx(), esc_attr__(), esc_html__(), _n_noop(), _nx_noop(), translate_nooped_plural().

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

Attachments (2)

48383.diff (1.4 KB) - added by atachibana 7 weeks ago.
48383.2.diff (3.1 KB) - added by SergeyBiryukov 7 weeks ago.

Download all attachments as: .zip

Change History (7)

@atachibana
7 weeks ago

#1 @atachibana
7 weeks ago

  • Keywords has-patch added

#2 @SergeyBiryukov
7 weeks ago

  • Description modified (diff)
  • Milestone changed from Awaiting Review to 5.4
  • Owner set to SergeyBiryukov
  • Status changed from new to reviewing

#3 @SergeyBiryukov
7 weeks ago

  • Keywords commit added

48383.2.diff includes some minor changes for consistency with existing comments.

#4 @atachibana
6 weeks ago

I verified the changes of 48383.2.diff.

#5 @SergeyBiryukov
6 weeks ago

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

In 46593:

Docs: Improve documentation for esc_attr_e(), esc_html_e(), esc_attr_x(), esc_html_x().

Props atachibana.
Fixes #48383.

Note: See TracTickets for help on using tickets.