Description: ------------ There is no good way to type hint a method which returns $this. Currently we only can specify the current class, which works fine, unless we extend the class, example: class Foo { function fooMethod() {} /** * @return Foo */ function fluentMethod() { return $this; } } class Bar extends Foo { function barMethod() {} } $bar = new Bar(); // if you type the code below you will see a hint about // about fooMethod(), but not about barMethod() as there // is no way to type hint the dynamic nature of fluent // interfaces that return $this: $bar->fluentMethod()->... Suggested behavior and syntax: /** * @return self */ function fluentMethod() { return $this; } When the above syntax is used, Eclipse PDT will assume the return class is the same class that invokes the method, never mind where in the inheritance chain the method itself was declared. The same request was also filed for Eclipse PDT at: https://bugs.eclipse.org/bugs/show_bug.cgi?id=276082

The only affect this is expected to have in PhpDocumentor itself is that the return signature in the generated docs still links to the class where the method is documented. So, "@return Foo" and "@return $this" both show the method signature as "Foo fluentMethod()" in the docs generated by PhpDocumentor. The _need_ for this syntax is in the downstream handling by IDEs et al. Therefore, it needs to be _allowed_ by PhpDocumentor. (based on discussion on #pear)

Update: the usage of "@return $this" was discussed on #pear, so that's what my comment means. The Eclipse request and the verbiage on this PEAR request use the "@return self" syntax instead. Presumably, either/both could be acceptable.

Briefly discussed this in #pear, and I think for now the best solution is the least questionable option: "@return $this", only for non-static methods. As for @return self / static, this could be discussed and added later (best to leave it out in case it's decided it'll have different semantics than $this). The same comment was added to the corresponding Eclipse PDT enhancement request. Thanks for the quick response :)

@method hint for classes should also be considered: /** * @method $this title */ class Foo { protected $title; public function __call($method, array $params) { $this->$method = $params[0]; } } /** * @method $this description */ class Bar { protected $description; } $bar = new Bar(); $bar->title("test")->description("test");

No more feature work on phpDocumentor 1.x. Check out the new phpDocumentor 2.x (http://www.phpdoc.org/).