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

[atachibana]

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.

[SergeyBiryukov]

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

[atachibana]

I verified the changes of 48383.2.diff.

[SergeyBiryukov]

In 46593:

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

Props atachibana.
Fixes #48383.