[5.6] Update Route Facade docblocks to support all possible scenarios

[Korri]

Made some changes to the docblock of the Route facade and added some to the Illuminate\Routing\RouteRegistrar class in order to allow IDEs to recognize all the following (valid) scenarios:

$callback = function () {};// Make for some shorter code examples

Route::current();
Route::currentRouteName();
Route::currentRouteAction();
Route::bind('user', $callback);
Route::get('user/{name}', $callback)->where('name', '[A-Za-z]+')->name('test');
Route::match(['get', 'post'], '/', $callback)->name('test');
Route::any('foo', $callback)->name('test');
Route::view('/welcome', 'welcome')->name('test');
Route::redirect('/here', '/there', 301)->name('there');
Route::group(['middleware' => 'test'], $callback);
Route::middleware('first')->group($callback);
Route::middleware(['first', 'second'])->group($callback);
Route::domain('{account}.myapp.com')->group($callback);
Route::prefix('admin')->middleware('admin')->as('admin')->name('App\Controllers2')->group($callback);
Route::prefix('admin')->middleware('admin')->as('admin')->name('App\Controllers2')->get('/logout', $callback);

The main motication is to fix the following that is not recognized as valid by phpstorm after mergin pull request #24040 : Route::middleware('first')->group($callback);

[taylorotwell]

The facade docblocks are already becoming tiresome. :/

[browner12]

yah, this feels like it will become a maintenance nightmare

[ntzm]

How else do you expect people with IDEs and static analysis tools to deal with Laravel's facades?

[imbrish]

Sorry for being ignorant, but doesn't https://github.com/barryvdh/laravel-ide-helper solve this problem already?

[browner12]

I believe it does, but people probably are looking for a solution that doesn't require another dependency.

[Korri]

Out use case is that we use PHPStan, and with good dockblocks, it allows PHPStan to understand facades without any custom plugin.