PHP phpDoc 調べてみた
phpDocとは
phpDocとは、phpにおけるコメントの書き方の1つで、決まったルールでコメントを書くことでコードの詳細情報などを記述する方法です。
phpDocの書き方
phpDocは、/**・・・ */の形式でコメントを記述します。これ以外の形式は、phpDocとみなされないので注意してください。
基本的なコメント形式は以下の形式になります。
/**
* summary: ファイルやクラス、メソッドの機能を一行で説明します
*
* description: summaryよりも詳細な情報を記述します
*
* annotations: 情報をアノテーションで指定します。
*/summaryとdescriptionとannotationsで構成されます。annotationは＠で始まる特殊な指定方法です。
今回は、ファイル、クラス、プロパティ、メソッドでのphpDocの書き方をご紹介します。
なお、今回ご紹介するのはあくまで1例になりますので、どのアノテーションを指定するかなどは適宜変更してください。
ファイル
ファイルの例になります。
<?php
namespace App\Services;
/**
* ラジオ番組のビジネスロジックを実装する
*
* ラジオ番組の番組名の取得、確認などを行う
*
* @author ryota_segawa ryota_segawa@XXX.com ・・・①
* @version 1.0 ・・・②
* @link https:example.com ・・・③
* @copyright 2021 Ryota Segawa ・・・④
*/
①ファイルの著者を記述します。メールアドレスなど社内で連絡が取れる情報も記述すると良いと思います。
②ファイルのバージョンを記述します。
③ファイルに関連するリンクを記述します。
④コピーライトを記述します。
クラス
クラスの例になります。
/**
* ラジオ番組用のクラス ・・・①
*
* @package App\Servies ・・・②
* @author ryota_segawa ryota_segawa@XXX.com
* @version 1.0
*/
class RadioProgram
{
①クラスのコメントはdescriptionが省略されるケースが多々あります。
②名前空間を記述します。
プロパティ
プロパティの例になります。
/**
* @var int $radio_program_id ラジオ番組のID ・・・①
*/
private $radio_program_id;
①「型 プロパティ名 説明」でプロパティ情報を記述します。
メソッド
メソッドの例になります。
/**
* ラジオ番組名に「オールナイトニッポン」の文言が入っているかどうかチェックする
*
* @param string $programName ラジオ番組名 ・・・①
* @return bool ・・・②
*/
public static function checkIsAllNightNippon(string $programName)
{
$allnightNippon = 'オールナイトニッポン';
if (strpos($programName, $allnightNippon) === false) {
return false;
} else {
return true;
}
}
①引数の情報を記述します。
②返り値の情報を記述します。
以上！！！！！！！