Clarify return $this

[dereuromark]

Removed the arguable sentence We only typehint public methods, though, as typehinting is not cost-free. It now just reads: Arguments that expect objects or arrays can be typehinted.

Moved the part about types to the right place (Commenting Code).

Also added a section about cakephp/cakephp#3792

When returning the object itself, e.g. for chaining, one should use ``$this`` instead::

    /**
     * Foo function.
     *
     * @return $this
     */
    public function foo() {
        return $this;
    }