php / phpDoc - @return instance of $this class?

Question

How do I mark a method as "returns an instance of the current class" in my phpDoc?

In the following example my IDE (Netbeans) will see that setSomething always returns a foo object.

But that's not true if I extent the object - it'll return $this, which in the second example is a bar object not a foo object.

class foo {
    protected $_value = null;

    /**
     * Set something
     *
     * @param string $value the value
     * @return foo
     */
    public function setSomething($value) {
        $this->_value = $value;
        return $this;
    }
} 

$foo = new foo();
$out = $foo->setSomething();

So fine - setSomething returns a foo - but in the following example, it returns a bar..:

class bar extends foo {
    public function someOtherMethod(){}
}

$bar = new bar();
$out = $bar->setSomething();
$out->someOtherMethod(); // <-- Here, Netbeans will think $out
                         // is a foo, so doesn't see this other
                         // method in $out's code-completion

... it'd be great to solve this as for me, code completion is a massive speed-boost.

Anyone got a clever trick, or even better, a proper way to document this with phpDoc?

Answer 1

Thought I'd revisit this Q as I came across a couple of things.

Currently "return $this" isn't supported, but there is a PhpDoc request to add exactly that in v1.5:

http://pear.php.net/bugs/bug.php?id=16223

There's also a request for it in Eclipse PDT:

https://bugs.eclipse.org/bugs/show_bug.cgi?id=276082

Both are relatively old requests. I'm not going to get too excited about this being implemented any time soon, but here goes to hoping :) In the meantime, it seems there is no proper solution to this problem.