[Finder] document array use for locations

[mickaelandrieu]

Hi,

This pull request is valid from Symfony 2.7 to 3.2-dev.

The function Finder::in() accepts a string or array of string for look into multiple locations => https://github.com/symfony/symfony/blob/master/src/Symfony/Component/Finder/Finder.php

The other way described is valid, but shouldn't be recommended/documented.

Mickaël

[wouterj]

this no longer holds true.

I propose to merge the code examples (this one and the ones on line 80 & 89):

The location is the only mandatory criteria. It tells the finder which
directory to use for the search::

    $finder->in(__DIR__);

    // search in several locations
    $finder->in(array(__DIR__, '/elsewhere'));
    $finder->in(__DIR__)->in('/elsewhere');

    // use wildcard characters (it has to resolve to at least one directory path)
    $finder->in('src/Symfony/*/*/Resources');

Exclude directories from matching with the [...]

[mickaelandrieu]

Hmm, it's less readable...

Is it ok for you to suggest the 2 options ? See my update :)

[weaverryan]

👍 for Wouter's suggestion.

@mickaelandrieu we're including more code, with short comments to explain them, as we've found that people mostly scan to code-blocks anyways. This is a situation where this isn't a huge win, because the text between the paragraphs is so short, but I still like.

[weaverryan]

Except for one change:

// search inside *both* directories
$finder->in(array(__DIR__, '/elsewhere'));
// same as above
$finder->in(__DIR__)->in('/elsewhere');

This is to be clear what calling in() twice does - it does not replace the previous directory.

[wouterj]

Thanks ,makes sense. We should still keep the reference to chaining though (e.g. when dynamically adding multiple directories), see my proposal.

Status: needs work

[stof]

multiple calls to ->in() are handy when you make these calls conditionally.

Thus, it is good to explain to the user what happens when calling it twice (some people might expect that it replaces the previous value entirely)

[weaverryan]

👍 for Wouter's version of this

Status: Reviewed

[xabbuh]

Thank you @mickaelandrieu. This is now merged. I also made a little tweak suggested by @weaverryan in 232ebc3.