Merge branch '5.4' into 6.0

* 5.4:
  Be more detailed about coding standards for PHPdoc

Author: javiereguiluz

contributing/code/standards.rst

@@ -47,30 +47,27 @@ short example containing most features described below::
      */
     class FooBar
     {
-        const SOME_CONST = 42;
+        public const SOME_CONST = 42;
 
         /**
          * @var string
          */
         private $fooBar;
-
         private $qux;
 
         /**
-         * @param string $dummy Some argument description
+         * @param $dummy some argument description
          */
-        public function __construct($dummy, Qux $qux)
+        public function __construct(string $dummy, Qux $qux)
         {
             $this->fooBar = $this->transformText($dummy);
             $this->qux = $qux;
         }
 
         /**
-         * @return string
-         *
          * @deprecated
          */
-        public function someDeprecatedMethod()
+        public function someDeprecatedMethod(): string
         {
             trigger_deprecation('symfony/package-name', '5.1', 'The %s() method is deprecated, use Acme\Baz::someMethod() instead.', __METHOD__);
 
@@ -80,14 +77,11 @@ short example containing most features described below::
         /**
          * Transforms the input given as the first argument.
          *
-         * @param bool|string $dummy   Some argument description
-         * @param array       $options An options collection to be used within the transformation
+         * @param $options an options collection to be used within the transformation
          *
-         * @return string|null The transformed input
-         *
-         * @throws \RuntimeException When an invalid option is provided
+         * @throws \RuntimeException when an invalid option is provided
          */
-        private function transformText($dummy, array $options = [])
+        private function transformText(bool|string $dummy, array $options = []): ?string
         {
             $defaultOptions = [
                 'some_default' => 'values',
@@ -100,16 +94,13 @@ short example containing most features described below::
                 }
             }
 
-            $mergedOptions = array_merge(
-                $defaultOptions,
-                $options
-            );
+            $mergedOptions = array_merge($defaultOptions, $options);
 
             if (true === $dummy) {
                 return 'something';
             }
 
-            if (is_string($dummy)) {
+            if (\is_string($dummy)) {
                 if ('values' === $mergedOptions['some_default']) {
                     return substr($dummy, 0, 5);
                 }
@@ -122,11 +113,8 @@ short example containing most features described below::
 
         /**
          * Performs some basic operations for a given value.
-         *
-         * @param mixed $value     Some value to operate against
-         * @param bool  $theSwitch Some switch to control the method's flow
          */
-        private function performOperations($value = null, $theSwitch = false)
+        private function performOperations(mixed $value = null, bool $theSwitch = false)
         {
             if (!$theSwitch) {
                 return;
@@ -162,6 +150,8 @@ Structure
 * Use ``return null;`` when a function explicitly returns ``null`` values and
   use ``return;`` when the function returns ``void`` values;
 
+* Do not add the ``void`` return type to methods in tests;
+
 * Use braces to indicate control structure body regardless of the number of
   statements it contains;
 
@@ -265,19 +255,28 @@ Service Naming Conventions
 Documentation
 ~~~~~~~~~~~~~
 
-* Add PHPDoc blocks for all classes, methods, and functions (though you may
-  be asked to remove PHPDoc that do not add value);
+* Add PHPDoc blocks for classes, methods, and functions only when they add
+  relevant information that does not duplicate the name, native type
+  declaration or context (e.g. ``instanceof`` checks);
+
+* Only use annotations and types defined in `the PHPDoc reference`_. In
+  order to improve types for static analysis, the following annotations are
+  also allowed:
+
+  * `Generics`_, with the exception of ``@template-covariant``.
+  * `Conditional return types`_ using the vendor-prefixed ``@psalm-return``;
+  * `Class constants`_;
+  * `Callable types`_;
 
 * Group annotations together so that annotations of the same type immediately
   follow each other, and annotations of a different type are separated by a
   single blank line;
 
-* Omit the ``@return`` tag if the method does not return anything;
-
-* The ``@package`` and ``@subpackage`` annotations are not used;
+* Omit the ``@return`` annotation if the method does not return anything;
 
-* Don't inline PHPDoc blocks, even when they contain just one tag (e.g. don't
-  put ``/** {@inheritdoc} */`` in a single line);
+* Don't use one-line PHPDoc blocks on classes, methods and functions, even
+  when they contain just one annotation (e.g. don't put ``/** {@inheritdoc} */``
+  in a single line);
 
 * When adding a new class or when making significant changes to an existing class,
   an ``@author`` tag with personal contact information may be added, or expanded.
@@ -303,3 +302,8 @@ License
 .. _`snake_case`: https://en.wikipedia.org/wiki/Snake_case
 .. _`constructor property promotion`: https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion
 .. _`trailing comma`: https://wiki.php.net/rfc/trailing_comma_in_parameter_list
+.. _`the PHPDoc reference`: https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html
+.. _`Conditional return types`: https://psalm.dev/docs/annotating_code/type_syntax/conditional_types/
+.. _`Class constants`: https://psalm.dev/docs/annotating_code/type_syntax/value_types/#regular-class-constants
+.. _`Callable types`: https://psalm.dev/docs/annotating_code/type_syntax/callable_types/
+.. _`Generics`: https://psalm.dev/docs/annotating_code/templated_annotations/