PHPDoc is 何

なぜ書くか

動的型付け言語に不足する部分を埋める

なにを書くか

1. 必須項目

型の情報

@var [型] 説明 @param [型] 変数名 説明 @return [型] 説明 (戻り値がない場合は省略可)

複数の型を返す場合にmixedと書けるが， これは避けたい. 複数の型を書く場合は, int|string|... のように記述できる.

- 型はなるべく具体的に書く

Builderと書いても * Core\Builder\Builder; * Illuminate\Database\Query\Builder など複数あり， 正しく判断できない場合がある．

- @return void is 何

voidは戻り値がないことを明示的に示す

例外オブジェクト

@throws [Exception Type] [説明]

メソッドが発行する例外オブジェクトを定義できる. これが書いてあると, メソッドを呼ぶときに, どのようなtry ~ catchを書くべきかを判断できる.

2. 必要に応じて書く項目

メソッドを実装する元になったやり取りへの参照

@link [url] [説明]

RedmineのチケットのURLやGitLabのissueなど