WordPress.org
Get WordPress

Make WordPress Core

Changeset 57734


Ignore:
Timestamp:
02/28/2024 09:29:03 AM (3 years ago)
Author:
swissspidy
Message:

I18N: Improve docs for pomo library classes.

Props subrataemfluence, pento, hrshahin.
Fixes #44424.

Location:
trunk/src/wp-includes/pomo
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/pomo/entry.php

    r56548 r57734  
    1111        /**
    1212         * Translation_Entry class encapsulates a translatable string.
     13         *
     14         * @since 2.8.0
    1315         */
    1416        #[AllowDynamicProperties]
    … …  
    7678                 * PHP4 constructor.
    7779                 *
     80                 * @since 2.8.0
    7881                 * @deprecated 5.4.0 Use __construct() instead.
    7982                 *
    … …  
    8790                /**
    8891                 * Generates a unique key for this entry.
     92                 *
     93                 * @since 2.8.0
    8994                 *
    9095                 * @return string|false The key or false if the entry is null.
    … …  
    104109
    105110                /**
    106                  * @param object $other
     111                 * Merges another translation entry with the current one.
     112                 *
     113                 * @since 2.8.0
     114                 *
     115                 * @param Translation_Entry $other Other translation entry.
    107116                 */
    108117                public function merge_with( &$other ) {

  • trunk/src/wp-includes/pomo/translations.php

    r57162 r57734  
    66 * @package pomo
    77 * @subpackage translations
     8 * @since 2.8.0
    89 */
    910
    … …  
    1213
    1314if ( ! class_exists( 'Translations', false ) ) :
     15        /**
     16         * Translations class.
     17         *
     18         * @since 2.8.0
     19         */
    1420        #[AllowDynamicProperties]
    1521        class Translations {
     22                /**
     23                 * List of translation entries.
     24                 *
     25                 * @since 2.8.0
     26                 *
     27                 * @var Translation_Entry[]
     28                 */
    1629                public $entries = array();
     30
     31                /**
     32                 * List of translation headers.
     33                 *
     34                 * @since 2.8.0
     35                 *
     36                 * @var array<string, string>
     37                 */
    1738                public $headers = array();
    1839
    1940                /**
    20                  * Add entry to the PO structure
     41                 * Adds an entry to the PO structure.
     42                 *
     43                 * @since 2.8.0
    2144                 *
    2245                 * @param array|Translation_Entry $entry
    23                  * @return bool true on success, false if the entry doesn't have a key
     46                 * @return bool True on success, false if the entry doesn't have a key.
    2447                 */
    2548                public function add_entry( $entry ) {
    … …  
    3659
    3760                /**
     61                 * Adds or merges an entry to the PO structure.
     62                 *
     63                 * @since 2.8.0
     64                 *
    3865                 * @param array|Translation_Entry $entry
    39                  * @return bool
     66                 * @return bool True on success, false if the entry doesn't have a key.
    4067                 */
    4168                public function add_entry_or_merge( $entry ) {
    … …  
    6289                 * TODO: this should be out of this class, it is gettext specific
    6390                 *
     91                 * @since 2.8.0
     92                 *
    6493                 * @param string $header header name, without trailing :
    6594                 * @param string $value header value, without trailing \n
    … …  
    7099
    71100                /**
    72                  * @param array $headers
     101                 * Sets translation headers.
     102                 *
     103                 * @since 2.8.0
     104                 *
     105                 * @param array $headers Associative array of headers.
    73106                 */
    74107                public function set_headers( $headers ) {
    … …  
    79112
    80113                /**
     114                 * Returns a given translation header.
     115                 *
     116                 * @since 2.8.0
     117                 *
    81118                 * @param string $header
     119                 * @return string|false Header if it exists, false otherwise.
    82120                 */
    83121                public function get_header( $header ) {
    … …  
    86124
    87125                /**
    88                  * @param Translation_Entry $entry
     126                 * Returns a given translation entry.
     127                 *
     128                 * @since 2.8.0
     129                 *
     130                 * @param Translation_Entry $entry Translation entry.
     131                 * @return Translation_Entry|false Translation entry if it exists, false otherwise.
    89132                 */
    90133                public function translate_entry( &$entry ) {
    … …  
    94137
    95138                /**
     139                 * Translates a singular string.
     140                 *
     141                 * @since 2.8.0
     142                 *
    96143                 * @param string $singular
    97144                 * @param string $context
    … …  
    118165                 * from their headers.
    119166                 *
    120                  * @param int $count number of items
     167                 * @since 2.8.0
     168                 *
     169                 * @param int $count Number of items.
     170                 * @return int Plural form to use.
    121171                 */
    122172                public function select_plural_form( $count ) {
    … …  
    125175
    126176                /**
    127                  * @return int
     177                 * Returns the plural forms count.
     178                 *
     179                 * @since 2.8.0
     180                 *
     181                 * @return int Plural forms count.
    128182                 */
    129183                public function get_plural_forms_count() {
    … …  
    132186
    133187                /**
     188                 * Translates a plural string.
     189                 *
     190                 * @since 2.8.0
     191                 *
    134192                 * @param string $singular
    135193                 * @param string $plural
    136194                 * @param int    $count
    137195                 * @param string $context
     196                 * @return string
    138197                 */
    139198                public function translate_plural( $singular, $plural, $count, $context = null ) {
    … …  
    158217
    159218                /**
    160                  * Merge $other in the current object.
    161                  *
    162                  * @param Object $other Another Translation object, whose translations will be merged in this one (passed by reference).
     219                 * Merges other translations into the current one.
     220                 *
     221                 * @since 2.8.0
     222                 *
     223                 * @param Translations $other Another Translation object, whose translations will be merged in this one (passed by reference).
    163224                 */
    164225                public function merge_with( &$other ) {
    … …  
    169230
    170231                /**
    171                  * @param object $other
     232                 * Merges originals with existing entries.
     233                 *
     234                 * @since 2.8.0
     235                 *
     236                 * @param Translations $other
    172237                 */
    173238                public function merge_originals_with( &$other ) {
    … …  
    182247        }
    183248
     249        /**
     250         * Gettext_Translations class.
     251         *
     252         * @since 2.8.0
     253         */
    184254        class Gettext_Translations extends Translations {
    185255
    … …  
    188258                 *
    189259                 * @var int
     260                 *
     261                 * @since 2.8.0
    190262                 */
    191263                public $_nplurals;
    … …  
    195267                 *
    196268                 * @var callable
     269                 *
     270                 * @since 2.8.0
    197271                 */
    198272                public $_gettext_select_plural_form;
    … …  
    201275                 * The gettext implementation of select_plural_form.
    202276                 *
    203                  * It lives in this class, because there are more than one descendand, which will use it and
     277                 * It lives in this class, because there are more than one descendant, which will use it and
    204278                 * they can't share it effectively.
    205279                 *
    206                  * @param int $count
     280                 * @since 2.8.0
     281                 *
     282                 * @param int $count Plural forms count.
     283                 * @return int Plural form to use.
    207284                 */
    208285                public function gettext_select_plural_form( $count ) {
    … …  
    216293
    217294                /**
     295                 * Returns the nplurals and plural forms expression from the Plural-Forms header.
     296                 *
     297                 * @since 2.8.0
     298                 *
    218299                 * @param string $header
    219                  * @return array
     300                 * @return array{0: int, 1: string}
    220301                 */
    221302                public function nplurals_and_expression_from_header( $header ) {
    … …  
    231312                /**
    232313                 * Makes a function, which will return the right translation index, according to the
    233                  * plural forms header
     314                 * plural forms header.
     315                 *
     316                 * @since 2.8.0
    234317                 *
    235318                 * @param int    $nplurals
    236319                 * @param string $expression
     320                 * @return callable
    237321                 */
    238322                public function make_plural_form_function( $nplurals, $expression ) {
    … …  
    250334                 * plural expressions, because PHP evaluates ternary operators from left to right
    251335                 *
     336                 * @since 2.8.0
    252337                 * @deprecated 6.5.0 Use the Plural_Forms class instead.
     338                 *
    253339                 * @see Plural_Forms
    254340                 *
    … …  
    282368
    283369                /**
     370                 * Prepare translation headers.
     371                 *
     372                 * @since 2.8.0
     373                 *
    284374                 * @param string $translation
    285                  * @return array
     375                 * @return array<string, string> Translation headers
    286376                 */
    287377                public function make_headers( $translation ) {
    … …  
    301391
    302392                /**
     393                 * Sets translation headers.
     394                 *
     395                 * @since 2.8.0
     396                 *
    303397                 * @param string $header
    304398                 * @param string $value
    … …  
    317411if ( ! class_exists( 'NOOP_Translations', false ) ) :
    318412        /**
    319          * Provides the same interface as Translations, but doesn't do anything
     413         * Provides the same interface as Translations, but doesn't do anything.
     414         *
     415         * @since 2.8.0
    320416         */
    321417        #[AllowDynamicProperties]
    322418        class NOOP_Translations {
     419                /**
     420                 * List of translation entries.
     421                 *
     422                 * @since 2.8.0
     423                 *
     424                 * @var Translation_Entry[]
     425                 */
    323426                public $entries = array();
     427
     428                /**
     429                 * List of translation headers.
     430                 *
     431                 * @since 2.8.0
     432                 *
     433                 * @var array<string, string>
     434                 */
    324435                public $headers = array();
    325436
    … …  
    329440
    330441                /**
     442                 * Sets a translation header.
     443                 *
     444                 * @since 2.8.0
     445                 *
    331446                 * @param string $header
    332447                 * @param string $value
    … …  
    336451
    337452                /**
     453                 * Sets translation headers.
     454                 *
     455                 * @since 2.8.0
     456                 *
    338457                 * @param array $headers
    339458                 */
    … …  
    342461
    343462                /**
     463                 * Returns a translation header.
     464                 *
     465                 * @since 2.8.0
     466                 *
    344467                 * @param string $header
    345468                 * @return false
    … …  
    350473
    351474                /**
     475                 * Returns a given translation entry.
     476                 *
     477                 * @since 2.8.0
     478                 *
    352479                 * @param Translation_Entry $entry
    353480                 * @return false
    … …  
    358485
    359486                /**
     487                 * Translates a singular string.
     488                 *
     489                 * @since 2.8.0
     490                 *
    360491                 * @param string $singular
    361492                 * @param string $context
    … …  
    366497
    367498                /**
     499                 * Returns the plural form to use.
     500                 *
     501                 * @since 2.8.0
     502                 *
    368503                 * @param int $count
    369                  * @return bool
     504                 * @return int
    370505                 */
    371506                public function select_plural_form( $count ) {
    … …  
    374509
    375510                /**
     511                 * Returns the plural forms count.
     512                 *
     513                 * @since 2.8.0
     514                 *
    376515                 * @return int
    377516                 */
    … …  
    381520
    382521                /**
     522                 * Translates a plural string.
     523                 *
     524                 * @since 2.8.0
     525                 *
    383526                 * @param string $singular
    384527                 * @param string $plural
    385528                 * @param int    $count
    386529                 * @param string $context
     530                 * @return string
    387531                 */
    388532                public function translate_plural( $singular, $plural, $count, $context = null ) {
    … …  
    391535
    392536                /**
    393                  * @param object $other
     537                 * Merges other translations into the current one.
     538                 *
     539                 * @since 2.8.0
     540                 *
     541                 * @param Translations $other
    394542                 */
    395543                public function merge_with( &$other ) {
Note: See TracChangeset for help on using the changeset viewer.