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?
Update:
As of Netbeans 7.4, the IDE supports @return self, static, and this (http://wiki.netbeans.org/NewAndNoteworthyNB74#Editor_2).
class foo {
protected $_value = null;
/**
* Set something
*
* @param string $value the value
* @return this
*/
public function setSomething($value) {
$this->_value = $value;
return $this;
}
}
class bar extends foo {
public function someOtherMethod(){}
}
Previous Answer:
We have a similar issue with a record iterator's current()
method. Since the iterator is extended for many different classes, it doesn't make sense to have a @return $class
associated with it. We've used @satrun77's Option 2 before, but I've used @method
with some success in Netbeans.
class foo {
protected $_value = null;
/**
* Set something
*
* @param string $value the value
* @return foo
*/
public function setSomething($value) {
$this->_value = $value;
return $this;
}
}
/**
* @method bar setSomething($value)
*/
class bar extends foo {
public function someOtherMethod(){}
}