minor #49432 Fix phpdocs in HttpClient, HttpFoundation, HttpKernel, I…

…ntl components (alamirault)

This PR was merged into the 5.4 branch.

Discussion
----------

Fix phpdocs in HttpClient, HttpFoundation, HttpKernel, Intl components

| Q             | A
| ------------- | ---
| Branch?       | 5.4
| Bug fix?      | no
| New feature?  | no <!-- please update src/**/CHANGELOG.md files -->
| Deprecations? | no <!-- please update UPGRADE-*.md and src/**/CHANGELOG.md files -->
| Tickets       | Fix #... <!-- prefix each issue number with "Fix #", no need to create an issue if none exists, explain below instead -->
| License       | MIT
| Doc PR        | symfony/symfony-docs#... <!-- required for new features -->

Fix phpdocs in HttpClient, HttpFoundation, HttpKernel, Intl components

Commits
-------

d4ff65e Fix phpdocs in HttpClient, HttpFoundation, HttpKernel, Intl components

src/Symfony/Component/HttpClient/AmpHttpClient.php

@@ -54,11 +54,11 @@ final class AmpHttpClient implements HttpClientInterface, LoggerAwareInterface,
     private $multi;
 
     /**
-     * @param array    $defaultOptions     Default requests' options
-     * @param callable $clientConfigurator A callable that builds a {@see DelegateHttpClient} from a {@see PooledHttpClient};
-     *                                     passing null builds an {@see InterceptedHttpClient} with 2 retries on failures
-     * @param int      $maxHostConnections The maximum number of connections to a single host
-     * @param int      $maxPendingPushes   The maximum number of pushed responses to accept in the queue
+     * @param array         $defaultOptions     Default requests' options
+     * @param callable|null $clientConfigurator A callable that builds a {@see DelegateHttpClient} from a {@see PooledHttpClient};
+     *                                          passing null builds an {@see InterceptedHttpClient} with 2 retries on failures
+     * @param int           $maxHostConnections The maximum number of connections to a single host
+     * @param int           $maxPendingPushes   The maximum number of pushed responses to accept in the queue
      *
      * @see HttpClientInterface::OPTIONS_DEFAULTS for available options
      */

src/Symfony/Component/HttpFoundation/Cookie.php

@@ -80,7 +80,7 @@ public static function create(string $name, string $value = null, $expire = 0, ?
      * @param string                        $name     The name of the cookie
      * @param string|null                   $value    The value of the cookie
      * @param int|string|\DateTimeInterface $expire   The time the cookie expires
-     * @param string                        $path     The path on the server in which the cookie will be available on
+     * @param string|null                   $path     The path on the server in which the cookie will be available on
      * @param string|null                   $domain   The domain that the cookie is available to
      * @param bool|null                     $secure   Whether the client should send back the cookie only over HTTPS or null to auto-enable this when the request is already using HTTPS
      * @param bool                          $httpOnly Whether the cookie will be made accessible only through the HTTP protocol

src/Symfony/Component/HttpFoundation/Request.php

@@ -439,12 +439,12 @@ public static function setFactory(?callable $callable)
     /**
      * Clones a request and overrides some of its parameters.
      *
-     * @param array $query      The GET parameters
-     * @param array $request    The POST parameters
-     * @param array $attributes The request attributes (parameters parsed from the PATH_INFO, ...)
-     * @param array $cookies    The COOKIE parameters
-     * @param array $files      The FILES parameters
-     * @param array $server     The SERVER parameters
+     * @param array|null $query      The GET parameters
+     * @param array|null $request    The POST parameters
+     * @param array|null $attributes The request attributes (parameters parsed from the PATH_INFO, ...)
+     * @param array|null $cookies    The COOKIE parameters
+     * @param array|null $files      The FILES parameters
+     * @param array|null $server     The SERVER parameters
      *
      * @return static
      */

src/Symfony/Component/HttpFoundation/Session/SessionInterface.php

@@ -59,10 +59,10 @@ public function setName(string $name);
      * Clears all session attributes and flashes and regenerates the
      * session and deletes the old session from persistence.
      *
-     * @param int $lifetime Sets the cookie lifetime for the session cookie. A null value
-     *                      will leave the system settings unchanged, 0 sets the cookie
-     *                      to expire with browser session. Time is in seconds, and is
-     *                      not a Unix timestamp.
+     * @param int|null $lifetime Sets the cookie lifetime for the session cookie. A null value
+     *                           will leave the system settings unchanged, 0 sets the cookie
+     *                           to expire with browser session. Time is in seconds, and is
+     *                           not a Unix timestamp.
      *
      * @return bool
      */
@@ -72,11 +72,11 @@ public function invalidate(int $lifetime = null);
      * Migrates the current session to a new session id while maintaining all
      * session attributes.
      *
-     * @param bool $destroy  Whether to delete the old session or leave it to garbage collection
-     * @param int  $lifetime Sets the cookie lifetime for the session cookie. A null value
-     *                       will leave the system settings unchanged, 0 sets the cookie
-     *                       to expire with browser session. Time is in seconds, and is
-     *                       not a Unix timestamp.
+     * @param bool     $destroy  Whether to delete the old session or leave it to garbage collection
+     * @param int|null $lifetime Sets the cookie lifetime for the session cookie. A null value
+     *                           will leave the system settings unchanged, 0 sets the cookie
+     *                           to expire with browser session. Time is in seconds, and is
+     *                           not a Unix timestamp.
      *
      * @return bool
      */

src/Symfony/Component/HttpFoundation/Session/Storage/Handler/NativeFileSessionHandler.php

@@ -19,9 +19,9 @@
 class NativeFileSessionHandler extends \SessionHandler
 {
     /**
-     * @param string $savePath Path of directory to save session files
-     *                         Default null will leave setting as defined by PHP.
-     *                         '/path', 'N;/path', or 'N;octal-mode;/path
+     * @param string|null $savePath Path of directory to save session files
+     *                              Default null will leave setting as defined by PHP.
+     *                              '/path', 'N;/path', or 'N;octal-mode;/path
      *
      * @see https://php.net/session.configuration#ini.session.save-path for further details.
      *

src/Symfony/Component/HttpFoundation/Session/Storage/MetadataBag.php

@@ -95,10 +95,10 @@ public function getLifetime()
     /**
      * Stamps a new session's metadata.
      *
-     * @param int $lifetime Sets the cookie lifetime for the session cookie. A null value
-     *                      will leave the system settings unchanged, 0 sets the cookie
-     *                      to expire with browser session. Time is in seconds, and is
-     *                      not a Unix timestamp.
+     * @param int|null $lifetime Sets the cookie lifetime for the session cookie. A null value
+     *                           will leave the system settings unchanged, 0 sets the cookie
+     *                           to expire with browser session. Time is in seconds, and is
+     *                           not a Unix timestamp.
      */
     public function stampNew(int $lifetime = null)
     {

src/Symfony/Component/HttpFoundation/Session/Storage/SessionStorageInterface.php

@@ -80,11 +80,11 @@ public function setName(string $name);
      * Otherwise session data could get lost again for concurrent requests with the
      * new ID. One result could be that you get logged out after just logging in.
      *
-     * @param bool $destroy  Destroy session when regenerating?
-     * @param int  $lifetime Sets the cookie lifetime for the session cookie. A null value
-     *                       will leave the system settings unchanged, 0 sets the cookie
-     *                       to expire with browser session. Time is in seconds, and is
-     *                       not a Unix timestamp.
+     * @param bool     $destroy  Destroy session when regenerating?
+     * @param int|null $lifetime Sets the cookie lifetime for the session cookie. A null value
+     *                           will leave the system settings unchanged, 0 sets the cookie
+     *                           to expire with browser session. Time is in seconds, and is
+     *                           not a Unix timestamp.
      *
      * @return bool
      *

src/Symfony/Component/HttpKernel/Fragment/HIncludeFragmentRenderer.php

@@ -30,7 +30,7 @@ class HIncludeFragmentRenderer extends RoutableFragmentRenderer
     private $charset;
 
     /**
-     * @param string $globalDefaultTemplate The global default content (it can be a template name or the content)
+     * @param string|null $globalDefaultTemplate The global default content (it can be a template name or the content)
      */
     public function __construct(Environment $twig = null, UriSigner $signer = null, string $globalDefaultTemplate = null, string $charset = 'utf-8')
     {

src/Symfony/Component/HttpKernel/HttpCache/SurrogateInterface.php

@@ -59,8 +59,8 @@ public function needsParsing(Response $response);
     /**
      * Renders a Surrogate tag.
      *
-     * @param string $alt     An alternate URI
-     * @param string $comment A comment to add as an esi:include tag
+     * @param string|null $alt     An alternate URI
+     * @param string      $comment A comment to add as an esi:include tag
      *
      * @return string
      */

src/Symfony/Component/Intl/DateFormatter/DateFormat/HourTransformer.php

@@ -25,8 +25,8 @@ abstract class HourTransformer extends Transformer
     /**
      * Returns a normalized hour value suitable for the hour transformer type.
      *
-     * @param int    $hour   The hour value
-     * @param string $marker An optional AM/PM marker
+     * @param int         $hour   The hour value
+     * @param string|null $marker An optional AM/PM marker
      *
      * @return int The normalized hour value
      */

src/Symfony/Component/Intl/DateFormatter/IntlDateFormatter.php

@@ -124,7 +124,7 @@ abstract class IntlDateFormatter
      * @param int|null                                $datetype Type of date formatting, one of the format type constants
      * @param int|null                                $timetype Type of time formatting, one of the format type constants
      * @param \IntlTimeZone|\DateTimeZone|string|null $timezone Timezone identifier
-     * @param int                                     $calendar Calendar to use for formatting or parsing. The only currently
+     * @param int|null                                $calendar Calendar to use for formatting or parsing. The only currently
      *                                                          supported value is IntlDateFormatter::GREGORIAN (or null using the default calendar, i.e. "GREGORIAN")
      * @param string|null                             $pattern  Optional pattern to use when formatting
      *
@@ -418,11 +418,11 @@ public function localtime(string $value, int &$position = 0)
     /**
      * Parse string to a timestamp value.
      *
-     * @param string $value    String to convert to a time value
-     * @param int    $position Not supported. Position at which to start the parsing in $value (zero-based)
-     *                         If no error occurs before $value is consumed, $parse_pos will
-     *                         contain -1 otherwise it will contain the position at which parsing
-     *                         ended. If $parse_pos > strlen($value), the parse fails immediately.
+     * @param string   $value    String to convert to a time value
+     * @param int|null $position Not supported. Position at which to start the parsing in $value (zero-based)
+     *                           If no error occurs before $value is consumed, $parse_pos will
+     *                           contain -1 otherwise it will contain the position at which parsing
+     *                           ended. If $parse_pos > strlen($value), the parse fails immediately.
      *
      * @return int|false Parsed value as a timestamp
      *
@@ -494,7 +494,7 @@ public function setLenient(bool $lenient)
     /**
      * Set the formatter's pattern.
      *
-     * @param string $pattern A pattern string in conformance with the ICU IntlDateFormatter documentation
+     * @param string|null $pattern A pattern string in conformance with the ICU IntlDateFormatter documentation
      *
      * @return bool true on success or false on failure
      *

src/Symfony/Component/Intl/Locale/Locale.php

@@ -152,8 +152,8 @@ public static function getDefault()
     /**
      * Not supported. Returns the localized display name for the locale language.
      *
-     * @param string $locale   The locale code to return the display language from
-     * @param string $inLocale Optional format locale code to use to display the language name
+     * @param string      $locale   The locale code to return the display language from
+     * @param string|null $inLocale Optional format locale code to use to display the language name
      *
      * @return string
      *
@@ -169,8 +169,8 @@ public static function getDisplayLanguage(string $locale, string $inLocale = nul
     /**
      * Not supported. Returns the localized display name for the locale.
      *
-     * @param string $locale   The locale code to return the display locale name from
-     * @param string $inLocale Optional format locale code to use to display the locale name
+     * @param string      $locale   The locale code to return the display locale name from
+     * @param string|null $inLocale Optional format locale code to use to display the locale name
      *
      * @return string
      *
@@ -186,8 +186,8 @@ public static function getDisplayName(string $locale, string $inLocale = null)
     /**
      * Not supported. Returns the localized display name for the locale region.
      *
-     * @param string $locale   The locale code to return the display region from
-     * @param string $inLocale Optional format locale code to use to display the region name
+     * @param string      $locale   The locale code to return the display region from
+     * @param string|null $inLocale Optional format locale code to use to display the region name
      *
      * @return string
      *
@@ -203,8 +203,8 @@ public static function getDisplayRegion(string $locale, string $inLocale = null)
     /**
      * Not supported. Returns the localized display name for the locale script.
      *
-     * @param string $locale   The locale code to return the display script from
-     * @param string $inLocale Optional format locale code to use to display the script name
+     * @param string      $locale   The locale code to return the display script from
+     * @param string|null $inLocale Optional format locale code to use to display the script name
      *
      * @return string
      *
@@ -220,8 +220,8 @@ public static function getDisplayScript(string $locale, string $inLocale = null)
     /**
      * Not supported. Returns the localized display name for the locale variant.
      *
-     * @param string $locale   The locale code to return the display variant from
-     * @param string $inLocale Optional format locale code to use to display the variant name
+     * @param string      $locale   The locale code to return the display variant from
+     * @param string|null $inLocale Optional format locale code to use to display the variant name
      *
      * @return string
      *
@@ -301,10 +301,10 @@ public static function getScript(string $locale)
     /**
      * Not supported. Returns the closest language tag for the locale.
      *
-     * @param array  $langtag      A list of the language tags to compare to locale
-     * @param string $locale       The locale to use as the language range when matching
-     * @param bool   $canonicalize If true, the arguments will be converted to canonical form before matching
-     * @param string $default      The locale to use if no match is found
+     * @param array       $langtag      A list of the language tags to compare to locale
+     * @param string      $locale       The locale to use as the language range when matching
+     * @param bool        $canonicalize If true, the arguments will be converted to canonical form before matching
+     * @param string|null $default      The locale to use if no match is found
      *
      * @see https://php.net/locale.lookup
      *

src/Symfony/Component/Intl/NumberFormatter/NumberFormatter.php

@@ -244,10 +244,10 @@ abstract class NumberFormatter
 
     /**
      * @param string|null $locale  The locale code. The only currently supported locale is "en" (or null using the default locale, i.e. "en")
-     * @param int         $style   Style of the formatting, one of the format style constants.
+     * @param int|null    $style   Style of the formatting, one of the format style constants.
      *                             The only supported styles are NumberFormatter::DECIMAL
      *                             and NumberFormatter::CURRENCY.
-     * @param string      $pattern Not supported. A pattern string in case $style is NumberFormat::PATTERN_DECIMAL or
+     * @param string|null $pattern Not supported. A pattern string in case $style is NumberFormat::PATTERN_DECIMAL or
      *                             NumberFormat::PATTERN_RULEBASED. It must conform to  the syntax
      *                             described in the ICU DecimalFormat or ICU RuleBasedNumberFormat documentation
      *
@@ -281,10 +281,10 @@ public function __construct(?string $locale = 'en', int $style = null, string $p
      * Static constructor.
      *
      * @param string|null $locale  The locale code. The only supported locale is "en" (or null using the default locale, i.e. "en")
-     * @param int         $style   Style of the formatting, one of the format style constants.
+     * @param int|null    $style   Style of the formatting, one of the format style constants.
      *                             The only currently supported styles are NumberFormatter::DECIMAL
      *                             and NumberFormatter::CURRENCY.
-     * @param string      $pattern Not supported. A pattern string in case $style is NumberFormat::PATTERN_DECIMAL or
+     * @param string|null $pattern Not supported. A pattern string in case $style is NumberFormat::PATTERN_DECIMAL or
      *                             NumberFormat::PATTERN_RULEBASED. It must conform to  the syntax
      *                             described in the ICU DecimalFormat or ICU RuleBasedNumberFormat documentation
      *
@@ -485,9 +485,9 @@ public function getTextAttribute(int $attr)
     /**
      * Not supported. Parse a currency number.
      *
-     * @param string $value    The value to parse
-     * @param string $currency Parameter to receive the currency name (reference)
-     * @param int    $position Offset to begin the parsing on return this value will hold the offset at which the parsing ended
+     * @param string   $value    The value to parse
+     * @param string   $currency Parameter to receive the currency name (reference)
+     * @param int|null $position Offset to begin the parsing on return this value will hold the offset at which the parsing ended
      *
      * @return float|false The parsed numeric value or false on error
      *

src/Symfony/Component/Intl/ResourceBundle.php

@@ -32,13 +32,13 @@ abstract protected static function getPath(): string;
      *
      * @see BundleEntryReaderInterface::readEntry()
      *
-     * @param string[] $indices  The indices to read from the bundle
-     * @param string   $locale   The locale to read
-     * @param bool     $fallback Whether to merge the value with the value from
-     *                           the fallback locale (e.g. "en" for "en_GB").
-     *                           Only applicable if the result is multivalued
-     *                           (i.e. array or \ArrayAccess) or cannot be found
-     *                           in the requested locale.
+     * @param string[]    $indices  The indices to read from the bundle
+     * @param string|null $locale   The locale to read
+     * @param bool        $fallback Whether to merge the value with the value from
+     *                              the fallback locale (e.g. "en" for "en_GB").
+     *                              Only applicable if the result is multivalued
+     *                              (i.e. array or \ArrayAccess) or cannot be found
+     *                              in the requested locale.
      *
      * @return mixed returns an array or {@link \ArrayAccess} instance for
      *               complex data and a scalar value for simple data