使用 phpDocumentor (phpdoc) 为 Laravel 包模型生成文档答案

【问题标题】：Generate documentation with phpDocumentor (phpdoc) for Laravel package model使用 phpDocumentor (phpdoc) 为 Laravel 包模型生成文档
【发布时间】：2021-10-22 08:50:51
【问题描述】：

我正在尝试使用 phpDocumentor 来生成我的 Laravel 包文档，但我发现生成面向使用的文档并不像我想的那样容易。

我的意思是：我应该如何编写 docblocks 以正确地让 php documentor 生成我的模型文档？ docblock 应该如何写 eloquent 和 laravel 特有的特性？

例如，目前在我的一个模型中，我用@ignore 标记了类$timestamps、$fillable、$appends 和$casts 属性以及附加属性的所有访问器，并在类中添加- 使用@property 标签对模型属性进行分级：

/**
 * @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
    }
}

这会生成更简单的文档，因为它从如何使用模型的角度显示/解释模型。

作用域和关系出现问题：我应该如何为那些（实际上）方法编写 docblock？
关系通常用作属性，期望它们返回模型或集合，但如果需要添加条件并期望返回关系实例，则可以再次用作函数。
作用域仍然用作函数，但使用不同的签名调用，因为第一个参数是从框架中注入的，甚至名称也不同。

对于这种情况有约定吗？

【问题讨论】：

标签： laravel eloquent phpdoc documentation-generation phpdocumentor2

【解决方案1】：

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

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

你应该这样写范围。

【讨论】：

好的，这是一个起点，谢谢。而对于关系？有什么提示吗？
您需要查看您的 2 个数据库表与关系。在我可以写与模型 2 表的关系之后。