bug #32919 [Intl] Order alpha2 to alpha3 mapping + phpdoc fixes (ro0NL)

This PR was merged into the 4.3 branch.

Discussion
----------

[Intl] Order alpha2 to alpha3 mapping + phpdoc fixes

| Q             | A
| ------------- | ---
| Branch?       | 4.3
| Bug fix?      | yes
| New feature?  | no
| BC breaks?    | no     <!-- see https://symfony.com/bc -->
| Deprecations? | no
| Tests pass?   | yes    <!-- please add some, will be required by reviewers -->
| Fixed tickets | #32676 (review)
| License       | MIT
| Doc PR        | symfony/symfony-docs#... <!-- required for new features -->

includes #32918

Commits
-------

867e3de [Intl] Order alpha2 to alpha3 mapping + phpdoc fixes

src/Symfony/Component/Intl/Countries.php

@@ -31,13 +31,16 @@ final class Countries extends ResourceBundle
      *
      * This list only contains "officially assigned ISO 3166-1 alpha-2" country codes.
      *
-     * @return string[] an array of canonical ISO 3166 country codes
+     * @return string[] an array of canonical ISO 3166 alpha-2 country codes
      */
     public static function getCountryCodes(): array
     {
         return self::readEntry(['Regions'], 'meta');
     }
 
+    /**
+     * @param string $country Alpha2 country code
+     */
     public static function exists(string $country): bool
     {
         try {
@@ -50,6 +53,8 @@ public static function exists(string $country): bool
     }
 
     /**
+     * Get country name from alpha2 code.
+     *
      * @throws MissingResourceException if the country code does not exists
      */
     public static function getName(string $country, string $displayLocale = null): string
@@ -58,9 +63,11 @@ public static function getName(string $country, string $displayLocale = null): s
     }
 
     /**
+     * Get list of country names indexed with alpha2 codes as keys.
+     *
      * @return string[]
      */
-    public static function getNames($displayLocale = null)
+    public static function getNames($displayLocale = null): array
     {
         return self::asort(self::readEntry(['Names'], $displayLocale), $displayLocale);
     }

src/Symfony/Component/Intl/Languages.php

@@ -22,7 +22,7 @@
 final class Languages extends ResourceBundle
 {
     /**
-     * Returns all available languages.
+     * Returns all available languages as two-letter codes.
      *
      * Languages are returned as lowercase ISO 639-1 two-letter language codes.
      * For languages that don't have a two-letter code, the ISO 639-2
@@ -31,7 +31,7 @@ final class Languages extends ResourceBundle
      * A full table of ISO 639 language codes can be found here:
      * http://www-01.sil.org/iso639-3/codes.asp
      *
-     * @return string[] an array of canonical ISO 639 language codes
+     * @return string[] an array of canonical ISO 639-1 language codes
      */
     public static function getLanguageCodes(): array
     {
@@ -50,6 +50,8 @@ public static function exists(string $language): bool
     }
 
     /**
+     * Get language name from alpha2 code.
+     *
      * @throws MissingResourceException if the language code does not exists
      */
     public static function getName(string $language, string $displayLocale = null): string
@@ -58,6 +60,8 @@ public static function getName(string $language, string $displayLocale = null):
     }
 
     /**
+     * Get list of language names indexed with alpha2 codes as keys.
+     *
      * @return string[]
      */
     public static function getNames(string $displayLocale = null): array
@@ -66,7 +70,7 @@ public static function getNames(string $displayLocale = null): array
     }
 
     /**
-     * Returns the ISO 639-2 three-letter code of a language.
+     * Returns the ISO 639-2 three-letter code of a language, given a two-letter code.
      *
      * @throws MissingResourceException if the language has no corresponding three-letter code
      */

src/Symfony/Component/Intl/Locales.php

@@ -67,7 +67,7 @@ public static function getName(string $locale, string $displayLocale = null): st
     /**
      * @return string[]
      */
-    public static function getNames($displayLocale = null)
+    public static function getNames($displayLocale = null): array
     {
         return self::asort(self::readEntry(['Names'], $displayLocale), $displayLocale);
     }

src/Symfony/Component/Intl/Scripts.php

@@ -51,7 +51,7 @@ public static function getName(string $script, string $displayLocale = null): st
     /**
      * @return string[]
      */
-    public static function getNames($displayLocale = null)
+    public static function getNames($displayLocale = null): array
     {
         return self::asort(self::readEntry(['Names'], $displayLocale), $displayLocale);
     }

src/Symfony/Component/Intl/Tests/LanguagesTest.php

@@ -645,32 +645,27 @@ class LanguagesTest extends ResourceBundleTestCase
         'ab' => 'abk',
         'af' => 'afr',
         'ak' => 'aka',
-        'sq' => 'sqi',
         'am' => 'amh',
         'ar' => 'ara',
         'an' => 'arg',
-        'hy' => 'hye',
         'as' => 'asm',
         'av' => 'ava',
         'ae' => 'ave',
         'ay' => 'aym',
         'az' => 'aze',
         'ba' => 'bak',
         'bm' => 'bam',
-        'eu' => 'eus',
         'be' => 'bel',
         'bn' => 'ben',
         'bi' => 'bis',
         'bo' => 'bod',
         'bs' => 'bos',
         'br' => 'bre',
         'bg' => 'bul',
-        'my' => 'mya',
         'ca' => 'cat',
         'cs' => 'ces',
         'ch' => 'cha',
         'ce' => 'che',
-        'zh' => 'zho',
         'cu' => 'chu',
         'cv' => 'chv',
         'kw' => 'cor',
@@ -680,13 +675,12 @@ class LanguagesTest extends ResourceBundleTestCase
         'da' => 'dan',
         'de' => 'deu',
         'dv' => 'div',
-        'nl' => 'nld',
         'dz' => 'dzo',
-        'et' => 'est',
         'el' => 'ell',
         'en' => 'eng',
         'eo' => 'epo',
-        'ik' => 'ipk',
+        'et' => 'est',
+        'eu' => 'eus',
         'ee' => 'ewe',
         'fo' => 'fao',
         'fa' => 'fas',
@@ -695,8 +689,6 @@ class LanguagesTest extends ResourceBundleTestCase
         'fr' => 'fra',
         'fy' => 'fry',
         'ff' => 'ful',
-        'om' => 'orm',
-        'ka' => 'kat',
         'gd' => 'gla',
         'ga' => 'gle',
         'gl' => 'glg',
@@ -711,32 +703,34 @@ class LanguagesTest extends ResourceBundleTestCase
         'ho' => 'hmo',
         'hr' => 'hrv',
         'hu' => 'hun',
+        'hy' => 'hye',
         'ig' => 'ibo',
-        'is' => 'isl',
         'io' => 'ido',
         'ii' => 'iii',
         'iu' => 'iku',
         'ie' => 'ile',
         'ia' => 'ina',
         'id' => 'ind',
+        'ik' => 'ipk',
+        'is' => 'isl',
         'it' => 'ita',
         'jv' => 'jav',
         'ja' => 'jpn',
         'kl' => 'kal',
         'kn' => 'kan',
         'ks' => 'kas',
+        'ka' => 'kat',
         'kr' => 'kau',
         'kk' => 'kaz',
-        'mn' => 'mon',
         'km' => 'khm',
         'ki' => 'kik',
         'rw' => 'kin',
         'ky' => 'kir',
-        'ku' => 'kur',
-        'kg' => 'kon',
         'kv' => 'kom',
+        'kg' => 'kon',
         'ko' => 'kor',
         'kj' => 'kua',
+        'ku' => 'kur',
         'lo' => 'lao',
         'la' => 'lat',
         'lv' => 'lav',
@@ -746,40 +740,43 @@ class LanguagesTest extends ResourceBundleTestCase
         'lb' => 'ltz',
         'lu' => 'lub',
         'lg' => 'lug',
-        'mk' => 'mkd',
         'mh' => 'mah',
         'ml' => 'mal',
-        'mi' => 'mri',
         'mr' => 'mar',
-        'ms' => 'msa',
+        'mk' => 'mkd',
         'mg' => 'mlg',
         'mt' => 'mlt',
+        'mn' => 'mon',
+        'mi' => 'mri',
+        'ms' => 'msa',
+        'my' => 'mya',
         'na' => 'nau',
         'nv' => 'nav',
         'nr' => 'nbl',
         'nd' => 'nde',
         'ng' => 'ndo',
         'ne' => 'nep',
+        'nl' => 'nld',
         'nn' => 'nno',
         'nb' => 'nob',
         'ny' => 'nya',
         'oc' => 'oci',
         'oj' => 'oji',
         'or' => 'ori',
+        'om' => 'orm',
         'os' => 'oss',
         'pa' => 'pan',
-        'ps' => 'pus',
         'pi' => 'pli',
         'pl' => 'pol',
         'pt' => 'por',
+        'ps' => 'pus',
         'qu' => 'que',
         'rm' => 'roh',
         'ro' => 'ron',
         'rn' => 'run',
         'ru' => 'rus',
         'sg' => 'sag',
         'sa' => 'san',
-        'sr' => 'srp',
         'si' => 'sin',
         'sk' => 'slk',
         'sl' => 'slv',
@@ -790,7 +787,9 @@ class LanguagesTest extends ResourceBundleTestCase
         'so' => 'som',
         'st' => 'sot',
         'es' => 'spa',
+        'sq' => 'sqi',
         'sc' => 'srd',
+        'sr' => 'srp',
         'ss' => 'ssw',
         'su' => 'sun',
         'sw' => 'swa',
@@ -820,6 +819,7 @@ class LanguagesTest extends ResourceBundleTestCase
         'yi' => 'yid',
         'yo' => 'yor',
         'za' => 'zha',
+        'zh' => 'zho',
         'zu' => 'zul',
     ];