Generate documentation with phpDocumentor (phpdoc) for Laravel package model

Question

I'm trying to use phpDocumentor to generate my Laravel package documentation, but I'm finding not-as-easy-as-I-tought to generate a usage-oriented documentation.

What i mean is: how should I write docblocks to correctly have php documentor genearate my models documentation? How should docblock be written for eloquent and laravel specific features?

As an example, currently in one of my models I tagged with @ignore the class $timestamps, $fillable, $appends and $casts properties and all the accessors to the appended attributes, and added at class-level the model attributes using the @property tag:

/**
 * @property string $a
 * @property float $b
 * @property-read bool $c
 * @property-read bool $d
 */
class MyModel extends Model
{

    /** @ignore */
    public $timestamps = false;

    /** @ignore */
    protected $fillable = [
        'a',
        'b',
    ];

    /** @ignore */
    protected $appends = [];

    /** @ignore */
    protected $casts = [];

    /** @ignore */
    public function getCAttribute(): bool
    {
        // return something
    }

    /** @ignore */
    public function getDAttribute(): bool
    {
        // return something
    }
}

This generate a simpler documentations, since it show/explain the model from the point of view of how to use it.

The problem arise with scopes and relations: how should I write docblock for those (actually) methods?
Relations are commonly used as attributes expecting them to return a Model or a Collection, but can be used again as functions if adding conditions is needed and expecting a Relation instance in return.
Scopes are still used as functions, but called with a different signature since the first argument is injected from the framework and even the name is different.

Is there a convention about this situation?

Answer 1

/**
 * @method static $scopeDa()
 */

public function scopeDa($query)
{
    return $query->where("a", "=", "conditional")->whereNull("deleted_at")->first();
}

You should write scope like that.