PHPDocの@inheritDocと{@inheritDoc}の違いについて

はじめに

最近PHPDocを眺める機会が増えて、その中で@inheritDocと{@inheritDoc}が登場し、同じでは？って思いながら調べた結果を残しておきます。

@inheritDocと{@inheritDoc}の違い

ドラフトではあるけど、PSR-19 PHPDoc Tagsに違いが書かれていました。

https://www.php-fig.org/psr/

@inheritDocとは

https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#41-making-inheritance-explicit-using-the-inheritdoc-tag

以下の例のようにPHPDocの内容に変更がない場合は@inheritDocを使って親クラスの内容を継承することができる。

class A {
    /**
     * 指定したidを使ってデータベースから値を取得する
     * @param int $id
     * @return array
     */
    public function get(int $id): array {
        // 処理
    }
}

class AA extends A {
    /**
     * @inheritDoc
     */
    public function get(int $id): array {
        // 処理
    }
}

{@inheritDoc}とは

https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md#42-using-the-inheritdoc-inline-tag-to-augment-a-description

親クラスの内容を継承し、情報を追加する場合に使う。

class A {
    /**
     * 指定したidを使ってデータベースから値を取得する
     * @param int $id
     * @return array
     */
    public function get(int $id): array {
        // 処理
    }
}

class AA extends A {
    /**
     * {@inheritDoc}
     * キャッシュがあればキャッシュから取得する
     */
    public function get(int $id): array {
        // 処理
    }
}

まとめ

違いましたね。
今まで使い分けを考えてなかったですが、雑に考えると次のような感じでしょうか？

• @inheritDocはドキュメントを継承する時に使う
• {@inheritDoc}はドキュメントを継承し、さらに情報を追加する時に使う

個人的には細く使い分けるより、どちらかに統一して書く方が良いと思いました。