Clarify return $this

Moved the part about types to the right place (Commenting Code).

Also added a section about https://github.com/cakephp/cakephp/pull/3792
```
When returning the object itself, e.g. for chaining, one should use ``$this`` instead::

    /**
     * Foo function.
     *
     * @return $this
     */
    public function foo() {
    	return $this;
    }
```