PHPerのための「PHPDoc について語り合う」PHP TechCafe

PHPers News


PHPDoc

参考資料

https://tech-blog.rakus.co.jp/entry/20210326/php

PHPDocとは

  • 以下ようなブロックの説明としてコード内に残すコメントのこと
    • 関数
    • 定数
    • クラス
    • メソッド
    • プロパティ
    • etc
  • 基本的にはただのコメント(:プログラムに影響はしない)
  • 一部のツールではPHPDocの内容によって処理を行うものも

活用例

  • 編集者の理解が捗る
  • IDEで補完が効きやすくなる
  • 静的解析がより正確に実行できる
  • 実行時に型チェックされる
    • 予期しない値が渡されることを防げる

記述ルール

  • 明確なルールは決まっていない
    • 各ツールごとに対応していない記述方式もある
  • PHPのドキュメントジェネレータであるphpDocumentorの記述がデファクトスタンダード?
  • PSR-5 や PSR-19 で標準化の議論は行われていた(2021/05現在 ドラフト状態)

代表的な書き方

基本的なタグ

@から始まる文字列。何についてのドキュメントかを示す。

  • @param:関数またはメソッドの引数について記述
  • @return:返り値について記述
  • @throws:例外について記述
  • @var:変数について記述
  • @todo:開発でやるべきことがあることを示す

型の記述

前述の タグ の後に記述することで、対象の型を記述する

@return int 整数を返す
  • リテラル型
    • int, bool, string etc
  • 配列型
    • ただの配列(中身不明): array
    • 数値キーの配列: int[]
    • 複数の方があり得る配列: (int|string)[]
    • 文字列キーの配列: array<string, int>
    • キーごとに値の型が異なる配列: array{id: int, name: string}

その他の書き方

false型

booleanではなくfalse型

property

__get(), __set()を使った動的なプロパティを記述することが可能

ローカル変数の型指定

@var で指定

Select a repo