id	summary	reporter	owner	description	type	status	priority	milestone	component	version	severity	resolution	keywords	cc	focuses	prnumber
48383	PHPDoc correction for l10n functions (esc_attr_e, esc_html_e, esc_attr_x and esc_html_x) in wp-includes/l10n.php	atachibana	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.
"	defect (bug)	closed	normal	5.4	I18N		minor	fixed	has-patch commit		docs