laravel/framework — pull request #5299 by barryvdh (2014-08-01 12:33:43+00:00)
Title: [PHPDoc] Update phpdocs for better chaining (return $this)

[PSR-5 Proposal](https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#keyword) suggests `self`, `static` and `$this`, with `self` for returning a class with the same type wherein the method is defined, `static` when it returns the same class as the class the method is called on, `$this` when it returns the same instance, so mostly for chaining methods.

PhpStorm: supports `self`, `static`, `$this` ([ticket](http://youtrack.jetbrains.com/issue/WI-2225))
Scrutinizer: supports `self`, `static`, `$this` (https://github.com/scrutinizer-ci/php-analyzer/issues/45 )
Netbeans: doesn't support `$this` but `this` (and `self`/`static`), but this is wrong and should be fixed by Netbeans ([bug](https://netbeans.org/bugzilla/show_bug.cgi?id=239987))
Eclipse supports `$this` also. (https://github.com/symfony/symfony/pull/11523)

Drupal has also taken `static` and `$this` up in their coding standards 6 months ago ([Discussion](https://www.drupal.org/node/2158497) / [CS Guide](https://www.drupal.org/coding-standards/docs#types)

So I suggest we follow the PSR-5 proposal and use `@return $this` for chaining methods. (and `static` for when a new instance is returned, eg. a new Collection)

I searched for any methods with explicitly having 'return $this;', so this might not be complete, but should cover a lot of cases. Also fixed some incorrect phpdocs when I saw them.