【PHP】PHPDocの書き方

PHP

PHPDocの書き方を紹介します。
他の開発者にもどういう意図で作られたファイルなのかをわかりやすくするためのものです。
関数実行の部分でカーソルをあわせるとVSCodeならそのPHPDocの説明をポップアップで表示させることができます。

PHPDocの書き方

<?php 
/**
 * 消費税込みの値段を算出するためのファイル
 * 
 * @author daredare (著者名)
 * @since 1.0.0 (バージョン)
 * 
 * 
 */

$price = 2000;


/**
 * 消費税込みの金額を取得する関数
 * 
 * 詳しい説明があればここにかく
 * 
 * @param int $basePrice 価格
 * @param int $taxRate 税率
 * 
 * @return int 税込金額
 * @return void (戻り値がない場合はvoidと書く)
 * @see https://zonuexe.github.io/phpDocumentor2-ja/references/phpdoc/index.html
 */
function withTax($basePrice, $taxRate = 0.1) {
  $sumPrice = $basePrice + ($basePrice * $taxRate);
  // 少数点以下を四捨五入する
  $sumPrice = round($sumPrice);

  return $sumPrice;
}

//文字列にしても実行できる
$price = "withTax3"($price);
echo "金額は{$price}です。";
//金額は2200です。

withTax($price);
$fn = "withTax3";
$price2 = $fn($price);
echo "金額は{$price2}です。";
//金額は2420です。

/**
*
*/
このスラッシュとアスタリスクの塊でPHPのDocコメントとみなされます。

そして、どういうファイルなのかを記述します。

PHPDocで使えるアノテーション

アノテーションとは、@○○といった表記の部分です。

アノテーションのリストは以下のサイトがわかりやすいです。
https://zonuexe.github.io/phpDocumentor2-ja/references/phpdoc/index.html

いくつか頻繁に使うアニメーションがあるので紹介します。

関数の引数を意味する　@param

@paramは引数です。
@paramのあとに、型、引数となる変数名を記述し、簡単な説明を書きます。
説明部分はあまり長くならないことが望ましいです。

関数の戻り値を意味する @return

@returnは、戻り値がある場合に記載します。
戻り値がない場合は、省略しても大丈夫ですし、voidと記載することで戻り値がないことを意味します。
@returnのあとに、型を記述します。変数名は書かなくて大丈夫です。
そして、簡単な説明を書きます。

参考資料を意味する @see

なにか参考資料がある場合は、@seeにURLなどをつけます。

実際には開発現場でルールがあるので、それに従って書きます。

PHP

Posted by devsakaso