この記事では、PHPDocの書き方からドキュメントを自動生成する方法について紹介しています！
PHPDocとは、DocComment（「/** */」で括られるコメント）内に記述する書式の通称です。
PHPDocを書くことで、
- クラスやメソッドの処理内容を把握しやすくなる
- コード補完やエラーチェックを行ってくれる
- PHPStanのような静的解析ツールの精度向上に貢献できる
- ドキュメントを自動生成できる
といったメリットがあります。
PHPDocの簡単な説明と、PHPDocを書くメリットを説明したところで、実際にPHPDocの書き方と、ドキュメントを自動生成する方法について紹介していきます！
PHPDocの書き方
PHPDocの書き方について紹介していきます。ちなみに公式ドキュメントは、こちら（phpDocumentor）になります。
前提知識
冒頭でも紹介したように、PHPDocは、「/** */」の形式でコメントを書きます。例えば以下のような記述です。
/**
* これは例です
*/1行で書くこともできます。
/** これは例です */PHPDocで使えるタグ（アノテーション）
ここからはPHPDocで使えるタグ（アノテーション）について紹介していきます！
タグとは、IDEや外部ツール、あるいはアプリケーション自身が要素をどのように解釈するかを知るためのメタデータを表します。
タグを全て紹介するのは荷が重いので、よく使うタグについてここでは紹介していきます！
タグに関しては、リファレンスページ（Tag reference）に一覧が載っているので、気になる方は見てみてください。
@var
@varタグは、定数やプロパティ、変数の値として、どのタイプのデータを表現するのかを定義します。
構文
@var ["Type"] [element_name] [<description>]実例
/** @var string $sample これはサンプルです */
private string $sample;@param
@paramタグは、関数やメソッドの引数の型と引数の変数名、説明を定義します。
構文
@param [<Type>] [name] [<description>]実例
/**
* サンプルを取得する
*
* @param int $sampleId サンプルID
*/
public function getSampleById(int $sampleId)
{
// 処理
}@return
@returnタグは、関数やメソッドの戻り値に関する情報を定義します。変数名は書かなくて大丈夫です。
構文
@return [Type] [<description>]実例
/**
* サンプル名を取得する
*
* @param int $sampleId サンプルID
* @return string サンプル名
*/
public function getSampleNameById(int $sampleId): string
{
// 処理
}戻り値がない場合は、@returnタグを書く必要はなく、暗黙的に @return void となります。
戻り値の複数の型が想定される場合は、@return string|array と書くことができます。ただ、そういった場合は、mixed型を使えば良いので、@return mixed と書いてあげれば良いですね。
@throws
@throwsタグは、関数やメソッドが投げる例外を定義します。
@throwsタグが記載されていることで、開発者は例外処理（try 〜 catch）の判断がしやすくなります。
構文
@throws [Type] [<description>]実例
/**
* サンプル名を取得する
*
* @param int $sampleId サンプルID
* @return string サンプル名
* @throws NotFoundSampleException サンプルが存在しない場合
*/
public function getSampleNameById(int $sampleId): string
{
// 処理
return $sampleName;
}PHPDocの記述を楽にしてくれるVSCodeの拡張機能を紹介
VSCodeでは、PHPDocの記述を楽にしてくれる「PHP DocBlocker」という拡張機能があります。
クラスや関数、プロパティの上で「/**」を入力することで、そのあとの記述内容を自動補完してくれるので、VSCodeを使っている方は、ぜひインストールしてみてください！
phpDocumentorでドキュメントを自動生成する
ここまでは、PHPDocの書き方について紹介してきました。
phpDocumentorを使うことで、PHPDocからドキュメントを自動生成することができるので、その方法についても紹介していきます！
phpDocumentorのインストール
composer経由でphpdocumentorをインストールしようと思いましたが、phpDocumentorのREADME.mdを見たところ、composer経由でのインストールは非推奨とのことなので、pharを使ってインストールします。
$ cd vendor/bin
$ wget https://phpdoc.org/phpDocumentor.pharドキュメントの自動生成
次にドキュメントを生成するためのコマンドです。
$ php vendor/bin/phpDocumentor.phar -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY>dオプションでドキュメント生成対象のパス、tオプションでドキュメント生成先のパスを指定することができます。
$ php vendor/bin/phpDocumentor.phar -d app/Http/Controllers/Controller.php -t docs今回は、サンプル用に作成したコントローラファイルのドキュメントをdocsフォルダ配下に生成させてみました。
docs/filesフォルダ配下に「app-http-controllers-controller.html」が生成されているので、こちらをブラウザで開くと、以下のように自動生成されたドキュメントを確認することができます！
まとめ｜PHPDocの書き方からドキュメントを自動生成する方法
ここまで、「PHPDocの書き方からドキュメントを自動生成する方法」について紹介してきました。
PHPDocを書いたり、phpDocumentorを使ってドキュメントを作成しておくことで、新しいメンバーが入ってきた場合でも、コードの全体像を理解する助けになります。
PHPDocを書いて、phpDocumentorでドキュメントを生成すること自体、そこまで手間がかかることもないので、まだ導入されていない方は導入してみると良いかと思います！
コメント