[wp-trac] [WordPress Trac] #48383: PHPDoc correction for l10n functions (esc_attr_e, esc_html_e, esc_attr_x and esc_html_x) in wp-includes/l10n.php

[WordPress Trac]

#48383: PHPDoc correction for l10n functions (esc_attr_e, esc_html_e, esc_attr_x
and esc_html_x) in wp-includes/l10n.php
--------------------------+-----------------------------
 Reporter:  atachibana    |       Owner:  SergeyBiryukov
     Type:  defect (bug)  |      Status:  reviewing
 Priority:  normal        |   Milestone:  5.4
Component:  I18N          |     Version:
 Severity:  minor         |  Resolution:
 Keywords:  has-patch     |     Focuses:  docs
--------------------------+-----------------------------
Changes (by SergeyBiryukov):

 * owner:  (none) => SergeyBiryukov
 * status:  new => reviewing
 * milestone:  Awaiting Review => 5.4


Old description:

> 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.

New description:

 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.

--

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/48383#comment:2>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform