Ok, lets supposes that we are working with Eloquent, where it can be very helpful. I think about some possibilities that should be better.
The *scope-method* on Eloquent is described as "scope" + scope name, the " scopeFilterName()", for instance, is called only as "filterName()". The major question here is that the *scope-method* will receives a first parameter that the filterName() will not. While the scopeFilterName() signature is ($builder, [... $otherArguments]), The filterName() signature is only ([... $otherArguments]). *Then I suggests you describe it like that:* /** * @param Builder $builder The scope builder instance. * @param string $name The name to filter. * @param bool|null $strictness The strictness of filter. * @method filterName(*$name*, *$strictly = null*) */ public function scopeFilterName(*Builder $builder*, $name, $strictness = null) { ... } In my mind, it could works like a method aliases (that is partially the case). The IDE, for instance, will understand that on filterName() declares only two parameters that was described in the *generator-method*. *It should works basically like I do directly:* /** * @param string $name The name to filter. * @param bool|null $strictness The strictness of filter. */ public function filterName(*$name*, *$strictness = null*) { ... } *Now replying your questions:* - *Applying the @method and @property items on a class basis can deal with magic methods.* Yes, it'll do, but the problem is that the IDE can't understand that, or even a documentor. It'll understand as a magic method, but will not identify where it was declared. - *Will the arguments of the magic method be the same as the underlying method, or will there be extra/removed arguments?* As I mentined before, it can do it easily. Maybe there some case where it can receives more arguments, then you should declares it as part of the *magic-method*. /** * The lessArguments() is called from moreArguments() magically. * @param string $name This parameter is used only on moreArguments(). * @method moreArguments($name) */ public function lessArguments() { ... } - *Will the return type of the magic method be the same as the underlying method?* You can declare it on annotation (@method (?returnType) magicCall((... arguments)) (?extra-description)). *I think too about an alternative, that can handle that directly on class, as today.* Basically, you can annotate the *magic-owner* of method, like that: /** * @method magicChild() {magicParent} */ class MyClass { /** Description. */ public function magicParent() { ... } } It can be useful if you need declares that outside the class: /** * @method magicChild() {OtherClass::magicParent} */ -- You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group. To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscr...@googlegroups.com. To post to this group, send email to php-fig@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/e3f51167-b31b-4f7a-86fc-4149919da776%40googlegroups.com. For more options, visit https://groups.google.com/d/optout.