minor symfony#13516 Document that cache warmers now must return an array of files to preload (javiereguiluz)

This PR was submitted for the master branch but it was squashed and merged into the 5.1 branch instead.

Discussion
----------

Document that cache warmers now must return an array of files to preload

Fixes symfony#13493.

Commits
-------

a5d6e40 Document that cache warmers now must return an array of files to preload

Author: javiereguiluz

reference/dic_tags.rst

@@ -468,13 +468,25 @@ the :class:`Symfony\\Component\\HttpKernel\\CacheWarmer\\CacheWarmerInterface` i
     // src/Cache/MyCustomWarmer.php
     namespace App\Cache;
 
+    use App\Foo\Bar;
     use Symfony\Component\HttpKernel\CacheWarmer\CacheWarmerInterface;
 
     class MyCustomWarmer implements CacheWarmerInterface
     {
         public function warmUp($cacheDirectory)
         {
             // ... do some sort of operations to "warm" your cache
+
+            $filesAndClassesToPreload = [];
+            $filesAndClassesToPreload[] = Bar::class;
+
+            foreach (scandir($someCacheDir) as $file) {
+                if (!is_dir($file = $someCacheDir.'/'.$file)) {
+                    $filesAndClassesToPreload[] = $file;
+                }
+            }
+
+            return $filesAndClassesToPreload;
         }
 
         public function isOptional()
@@ -483,6 +495,16 @@ the :class:`Symfony\\Component\\HttpKernel\\CacheWarmer\\CacheWarmerInterface` i
         }
     }
 
+The ``warmUp()`` method must return an array with the files and classes to
+preload. Files must be absolute paths and classes must be fully-qualified class
+names. The only restriction is that files must be stored in the cache directory.
+If you don't need to preload anything, return an empty array
+
+.. deprecated:: 5.1
+
+    Not returning an array from the ``warmUp()`` method with the files to
+    preload is deprecated since Symfony 5.1.
+
 The ``isOptional()`` method should return true if it's possible to use the
 application without calling this cache warmer. In Symfony, optional warmers
 are always executed by default (you can change this by using the