WordPress.org
Get WordPress

Make WordPress Core

Changeset 57734


Ignore:
Timestamp:
02/28/2024 09:29:03 AM (2 months 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.