changed 3 years ago  
Linked with GitHub

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