minor #18719 Add SplFileInfo array doc on Finder iterator methods so …

…that IDE will known it (Haehnchen)

This PR was submitted for the master branch but it was merged into the 2.3 branch instead (closes #18719).

Discussion
----------

Add SplFileInfo array doc on Finder iterator methods so that IDE will known it

| Q             | A
| ------------- | ---
| Branch       | master
| Bug fix      | no
| New feature  | no
| BC breaks    | no
| Deprecations | no
| Tests pass   | yes
| Fixed tickets | #16965
| License       | MIT

Add support for IDE completion of Finder iterator in userland

see #16965, http://stackoverflow.com/questions/37034643/autocomplete-doesnt-work-on-symfonys-splfileinfofinder-method-in-foreach/37055206

Examples:
```php
$finder->size()->in()[0]->getContents();
foreach ($finder->size()->in() as $file) {
    $file->getContents();
}
```

Commits
-------

94b9e44 Add SplFileInfo array doc on Finder iterator methods so that IDE will know what it returns

src/Symfony/Component/Finder/Finder.php

@@ -171,7 +171,7 @@ public function getAdapters()
     /**
      * Restricts the matching to directories only.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      */
     public function directories()
     {
@@ -183,7 +183,7 @@ public function directories()
     /**
      * Restricts the matching to files only.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      */
     public function files()
     {
@@ -202,7 +202,7 @@ public function files()
      *
      * @param int $level The depth level expression
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see DepthRangeFilterIterator
      * @see NumberComparator
@@ -226,7 +226,7 @@ public function depth($level)
      *
      * @param string $date A date range string
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see strtotime
      * @see DateRangeFilterIterator
@@ -250,7 +250,7 @@ public function date($date)
      *
      * @param string $pattern A pattern (a regexp, a glob, or a string)
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see FilenameFilterIterator
      */
@@ -266,7 +266,7 @@ public function name($pattern)
      *
      * @param string $pattern A pattern (a regexp, a glob, or a string)
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see FilenameFilterIterator
      */
@@ -287,7 +287,7 @@ public function notName($pattern)
      *
      * @param string $pattern A pattern (string or regexp)
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see FilecontentFilterIterator
      */
@@ -308,7 +308,7 @@ public function contains($pattern)
      *
      * @param string $pattern A pattern (string or regexp)
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see FilecontentFilterIterator
      */
@@ -331,7 +331,7 @@ public function notContains($pattern)
      *
      * @param string $pattern A pattern (a regexp or a string)
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see FilenameFilterIterator
      */
@@ -354,7 +354,7 @@ public function path($pattern)
      *
      * @param string $pattern A pattern (a regexp or a string)
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see FilenameFilterIterator
      */
@@ -374,7 +374,7 @@ public function notPath($pattern)
      *
      * @param string $size A size range string
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see SizeRangeFilterIterator
      * @see NumberComparator
@@ -391,7 +391,7 @@ public function size($size)
      *
      * @param string|array $dirs A directory path or an array of directories
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see ExcludeDirectoryFilterIterator
      */
@@ -407,7 +407,7 @@ public function exclude($dirs)
      *
      * @param bool $ignoreDotFiles Whether to exclude "hidden" files or not
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see ExcludeDirectoryFilterIterator
      */
@@ -427,7 +427,7 @@ public function ignoreDotFiles($ignoreDotFiles)
      *
      * @param bool $ignoreVCS Whether to exclude VCS files or not
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see ExcludeDirectoryFilterIterator
      */
@@ -467,7 +467,7 @@ public static function addVCSPattern($pattern)
      *
      * @param \Closure $closure An anonymous function
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see SortableIterator
      */
@@ -483,7 +483,7 @@ public function sort(\Closure $closure)
      *
      * This can be slow as all the matching files and directories must be retrieved for comparison.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see SortableIterator
      */
@@ -499,7 +499,7 @@ public function sortByName()
      *
      * This can be slow as all the matching files and directories must be retrieved for comparison.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see SortableIterator
      */
@@ -517,7 +517,7 @@ public function sortByType()
      *
      * This can be slow as all the matching files and directories must be retrieved for comparison.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see SortableIterator
      */
@@ -537,7 +537,7 @@ public function sortByAccessedTime()
      *
      * This can be slow as all the matching files and directories must be retrieved for comparison.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see SortableIterator
      */
@@ -555,7 +555,7 @@ public function sortByChangedTime()
      *
      * This can be slow as all the matching files and directories must be retrieved for comparison.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see SortableIterator
      */
@@ -574,7 +574,7 @@ public function sortByModifiedTime()
      *
      * @param \Closure $closure An anonymous function
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @see CustomFilterIterator
      */
@@ -588,7 +588,7 @@ public function filter(\Closure $closure)
     /**
      * Forces the following of symlinks.
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      */
     public function followLinks()
     {
@@ -604,7 +604,7 @@ public function followLinks()
      *
      * @param bool $ignore
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      */
     public function ignoreUnreadableDirs($ignore = true)
     {
@@ -618,7 +618,7 @@ public function ignoreUnreadableDirs($ignore = true)
      *
      * @param string|array $dirs A directory path or an array of directories
      *
-     * @return Finder The current Finder instance
+     * @return Finder|SplFileInfo[] The current Finder instance
      *
      * @throws \InvalidArgumentException if one of the directories does not exist
      */
@@ -679,7 +679,7 @@ public function getIterator()
      *
      * @param mixed $iterator
      *
-     * @return Finder The finder
+     * @return Finder|SplFileInfo[] The finder
      *
      * @throws \InvalidArgumentException When the given argument is not iterable.
      */