PHPer は技術者のレベルの差が激しいと言われている言語です。
恥ずかしい思いをしないためにもDocコメントの基礎くらいは知っておきたいところです。
Docコメントのメリット
可読性・視認性が高くなる
何をするのか・どのようなデータを持っているのかなどが一目で分かる。
一目でわかるこそ、保守開発時には大いに役に立チマス。（正直これだけ書くモチベーションになれます。
ツールに影響する
PHPStan や PHPUnit などのツールを使用する際に大きく役に立つ。
特に静的解析の精度向上に役に立ち、バグの発生や早期発見にすんげぇ貢献してくれる。
やんやん
プログラマーとしてLEMP環境に主に生息しており、DevOps 的な立ち回りをしながらご飯を食べている当ブログの管理人のやんやんと申します。
最近はTmux使うのを辞めました。
Docコメントのデメリット
めんどくさい
Docコメントを書く事が猛烈にめんどくさい日がたまにあります。
メリットをちゃんと理解しているので、めんどくさい日でもちゃんと書きます。みなさんも書きましょう。
不適切な内容だとツラい
Docコメントに書いてある内容が間違っていると誤解を生み、新たな仕事を発生させることがある。
最近ではある大手のサービスのSDKのDocコメントが間違っており、IDE上の警告が消えないために時間を費やしてしまう事件がありました。（多分Docコメントのメンテナンスされていないだけかな…？）
みんなもキヲツケテネ。
書き方
こんな感じで書くよ。(改行がおかしいのは許してね)
/**
* 何をするメソッドなのか
*
* @param 変数
* @return 戻り値
*/
private function fuga(): void {}
/**
* プロパティの説明
*
* @var string
*/
protected string $hogehoge
型定義
| type | 説明 |
| string | 文字列 |
| integer / int | 整数 |
| boolean / bool | 真偽値 |
| float / double | 浮動小数点数 |
| object | 任意のクラスのインスタンス |
| mixed | 任意の型（不特定） |
| array | 配列 |
| resource | リソース型 |
| void | 値を返さない |
| null | NULL値 |
| callable | コールバック関数 |
| false / true | 真または偽 |
| self | 同じクラスのインスタンス |
| scalar | スカラー型（string, int, boolなど） |
参考：https://docs.phpdoc.org/3.0/guide/references/phpdoc/types.html
タグの意味
| Tag Name | 意味 | 用法の例 |
| @param | パラメータを記述 ※メソッドのDocコメントに使ったりするよ |
@param int $age 年齢 |
| @return | 戻り値を記述 | @return string ユーザーの名前を返します |
| @var | 変数の型を記述 ※プロパティのDocコメントに使ったりするよ |
@var string $name ユーザーの名前 |
| @throws | 例外を記述 | @throws InvalidArgumentException 不正な引数の場合 |
| @deprecated | 非推奨を示す | @deprecated 2.0.0バージョン以降で非推奨 |
| @see | 関連要素を参照 | @see User::getName() 関連するメソッド |
| @author | 作者名 | @author 山田太郎 |
| @since | 導入されたバージョン | @since 1.0.0 初期バージョンから導入 |
| @version | バージョン | @version 1.2.3 |
| @link | 関連リンク | @link http://example.com 詳細情報 |
| @example | 例示 | @example /path/to/example.php 例示コード |
| @category | カテゴリ分類 | @category HTTP クライアント関連 |
参考：https://docs.phpdoc.org/3.0/guide/references/phpdoc/index.html
