feature #31996 [5.0] Add return types in final classes (dFayet)

This PR was merged into the 5.0-dev branch.

Discussion
----------

[5.0] Add return types in final classes

| Q             | A
| ------------- | ---
| Branch?       | master
| Bug fix?      | no
| New feature?  | yes/no <!-- please update src/**/CHANGELOG.md files -->
| BC breaks?    | no
| Deprecations? | no
| Tests pass?   | no
| Fixed tickets | #31981
| License       | MIT
| Doc PR        | symfony/symfony-docs#... <!-- required for new features -->

This is the first step for the issue #31981

I have some questions:

-  ~I have not added type for methods with `@inheritdoc` annotation, should I?~
- ~Don't we want to type also functions without `@return` annotation? (still in `final` classes)~
- ~If yes is the answer of the previous one, do we also want the `void` return type?~
- ~I have also added the return type in the `DependencyInjection` PhpDumper, but is it also wanted? (if yes, I will clean a bit the code changed)~
- ~Should we update the documentation's code samples when they display `final` classes?~

Todo:
- [x] Adjust the PR, following the answers of the questions
- [x] Add return type also when there is no `@return`, or with `@inheritdoc`
- [x] [src/Symfony/Component/Debug/ErrorHandler.php#L383](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Debug/ErrorHandler.php#L383) `@return` annotation is not correct according to the return, investigate and adjust if needed
- [x] [src/Symfony/Component/HttpKernel/ControllerMetadata/ArgumentMetadataFactory.php#L50](https://github.com/symfony/symfony/blob/master/src/Symfony/Component/HttpKernel/ControllerMetadata/ArgumentMetadataFactory.php#L50) `@return` annotation is not correct according to the return, investigate and adjust if needed
- [x] Do a PR on documentation to add return type on code snippets with final classes => unneeded as they were already typed

Commits
-------

ca5ae1989e Replace @return annotation by return type in final classes

Author: Tobion

CompiledRoute.php

@@ -66,7 +66,7 @@ public function __serialize(): array
     /**
      * @internal
      */
-    final public function serialize()
+    final public function serialize(): string
     {
         return serialize($this->__serialize());
     }

Loader/Configurator/CollectionConfigurator.php

@@ -47,10 +47,8 @@ public function __destruct()
 
     /**
      * Creates a sub-collection.
-     *
-     * @return self
      */
-    final public function collection($name = '')
+    final public function collection($name = ''): self
     {
         return new self($this->collection, $this->name.$name, $this, $this->prefixes);
     }
@@ -62,7 +60,7 @@ final public function collection($name = '')
      *
      * @return $this
      */
-    final public function prefix($prefix)
+    final public function prefix($prefix): object
     {
         if (\is_array($prefix)) {
             if (null === $this->parentPrefixes) {

Loader/Configurator/ImportConfigurator.php

@@ -41,7 +41,7 @@ public function __destruct()
      *
      * @return $this
      */
-    final public function prefix($prefix, bool $trailingSlashOnRoot = true)
+    final public function prefix($prefix, bool $trailingSlashOnRoot = true): object
     {
         if (!\is_array($prefix)) {
             $this->route->addPrefix($prefix);
@@ -84,7 +84,7 @@ final public function prefix($prefix, bool $trailingSlashOnRoot = true)
      *
      * @return $this
      */
-    final public function namePrefix(string $namePrefix)
+    final public function namePrefix(string $namePrefix): object
     {
         $this->route->addNamePrefix($namePrefix);
 

Loader/Configurator/RoutingConfigurator.php

@@ -33,10 +33,7 @@ public function __construct(RouteCollection $collection, PhpFileLoader $loader,
         $this->file = $file;
     }
 
-    /**
-     * @return ImportConfigurator
-     */
-    final public function import($resource, $type = null, $ignoreErrors = false)
+    final public function import($resource, $type = null, $ignoreErrors = false): ImportConfigurator
     {
         $this->loader->setCurrentDir(\dirname($this->path));
         $imported = $this->loader->import($resource, $type, $ignoreErrors, $this->file);
@@ -52,10 +49,7 @@ final public function import($resource, $type = null, $ignoreErrors = false)
         return new ImportConfigurator($this->collection, $mergedCollection);
     }
 
-    /**
-     * @return CollectionConfigurator
-     */
-    final public function collection($name = '')
+    final public function collection($name = ''): CollectionConfigurator
     {
         return new CollectionConfigurator($this->collection, $name);
     }

Loader/Configurator/Traits/RouteTrait.php

@@ -26,7 +26,7 @@ trait RouteTrait
      *
      * @return $this
      */
-    final public function defaults(array $defaults)
+    final public function defaults(array $defaults): object
     {
         $this->route->addDefaults($defaults);
 
@@ -38,7 +38,7 @@ final public function defaults(array $defaults)
      *
      * @return $this
      */
-    final public function requirements(array $requirements)
+    final public function requirements(array $requirements): object
     {
         $this->route->addRequirements($requirements);
 
@@ -50,7 +50,7 @@ final public function requirements(array $requirements)
      *
      * @return $this
      */
-    final public function options(array $options)
+    final public function options(array $options): object
     {
         $this->route->addOptions($options);
 
@@ -62,7 +62,7 @@ final public function options(array $options)
      *
      * @return $this
      */
-    final public function utf8(bool $utf8 = true)
+    final public function utf8(bool $utf8 = true): object
     {
         $this->route->addOptions(['utf8' => $utf8]);
 
@@ -74,7 +74,7 @@ final public function utf8(bool $utf8 = true)
      *
      * @return $this
      */
-    final public function condition(string $condition)
+    final public function condition(string $condition): object
     {
         $this->route->setCondition($condition);
 
@@ -86,7 +86,7 @@ final public function condition(string $condition)
      *
      * @return $this
      */
-    final public function host(string $pattern)
+    final public function host(string $pattern): object
     {
         $this->route->setHost($pattern);
 
@@ -101,7 +101,7 @@ final public function host(string $pattern)
      *
      * @return $this
      */
-    final public function schemes(array $schemes)
+    final public function schemes(array $schemes): object
     {
         $this->route->setSchemes($schemes);
 
@@ -116,7 +116,7 @@ final public function schemes(array $schemes)
      *
      * @return $this
      */
-    final public function methods(array $methods)
+    final public function methods(array $methods): object
     {
         $this->route->setMethods($methods);
 
@@ -130,7 +130,7 @@ final public function methods(array $methods)
      *
      * @return $this
      */
-    final public function controller($controller)
+    final public function controller($controller): object
     {
         $this->route->addDefaults(['_controller' => $controller]);
 
@@ -142,7 +142,7 @@ final public function controller($controller)
      *
      * @return $this
      */
-    final public function locale(string $locale)
+    final public function locale(string $locale): object
     {
         $this->route->addDefaults(['_locale' => $locale]);
 
@@ -154,7 +154,7 @@ final public function locale(string $locale)
      *
      * @return $this
      */
-    final public function format(string $format)
+    final public function format(string $format): object
     {
         $this->route->addDefaults(['_format' => $format]);
 

Route.php

@@ -80,7 +80,7 @@ public function __serialize(): array
     /**
      * @internal
      */
-    final public function serialize()
+    final public function serialize(): string
     {
         return serialize($this->__serialize());
     }