On Wednesday, March 29, 2017 at 6:48:10 PM UTC+2, David Rodrigues wrote:
>
> *The advantages:*
>
> 1. IDE could detects exactly "who" is the real method, then read all
> parameters related, description, etc.;
> 2. The @method return typehint is optional, when not declared, copy
> from real method, if declared, override that;
> 3. The @method parameters is optional, when not declared, copy from
> real method, if declared, override that;
>
> Mhm, lets consider a more suitable example from the eloquent docs
<https://laravel.com/docs/5.4/eloquent#local-scopes>
class User extends Model
{
/**
* Scope a query to only include users of a given type.
*
* @param \Illuminate\Database\Eloquent\Builder $query
* @param mixed $type
* @return \Illuminate\Database\Eloquent\Builder
*/
public function scopeOfType($query, $type)
{
return $query->where('type', $type);
}
}
$users = App\User::ofType('admin')->get();
Hence, IMO, none of your *advantages* are valid:
1. scopeOfType is not the *real* method; it is a method used to
*build/provide* an ofType method
2. does more harm than good, because of 1.
3. does more harm than good, because of 1.
Having said that, nonetheless, I believe you are right. It makes most sense
to document ofType as close as possible to scopeOfType:
class User extends Model
{
/**
* Scope a query to only include users of a given type.
*
* @param \Illuminate\Database\Eloquent\Builder $query
* @param mixed $type
* @return \Illuminate\Database\Eloquent\Builder
*/
/**
* @method $this ofType(mixed $type) {
* Only include users of a given type.
*
* @param mixed $type
* @return $this
* }
*/
public function scopeOfType($query, $type)
{
return $query->where('type', $type);
}
}
The only thing new about that would be the place; thus, if you want to
navigate to the declaration of ofType, then your IDE is able to navigate to
the @method comment – which is the most reasonable I can think of.
When I think about it, placing @method within the curly class brackets
makes more sense to me, than placing it before the class keyword anyway.
Bests,
Michael
--
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 [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit
https://groups.google.com/d/msgid/php-fig/b0ba7268-ff6d-434d-809d-995e08b078c3%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
