PHPのコメント形式のPHPDoc

phpDocumentor
PHPDoc reference — phpDocumentor
PHPDoc リファレンス — phpDocumentor
　PHPDocはphpには関数を表すためのコメントの形式として用意されているフォーマットです。PHPDocの形式に対応したコメントはIDEの様な多機能エディタでPHPファイルを編集する際に、読みやすい形になって出力されます。例えば次の様になります。

　関数の説明、引数の型と名前と説明、返り値の型と説明、どのファイルから呼ばれているかが整理されて記述されています。リンクを埋め込むこともできます。下図の様に、関数を呼び出すところでも同じ説明を出力できます。

　エディタによっては下図の様にPHPDocで指定された型と引数の型が異なる場合、警告を出力してくれます。
　
　PHPDocと認識されるフォーマットは次の様に/**と*/で括られ、各行頭に任意の数の空白文字と*がついたフォーマットです。

/**
 *
 */

　この中に説明と@から始まるタグを入れることで肉付けします。ここまでに上げた画像の様に関数に対してPHPDocを記述する場合、まず必要なのは@paramと@returnでしょう。それぞれ引数と返り値の説明です。関数内部の動作が正しいと仮定した場合、中身を読む必要はありません。適切な説明と引数、返り値がわかればそれだけで十分です。組み込み関数と同じですね。@paramと@returnの形式は

@param [型] 変数名 説明
@return [型] 説明

で、半角スペースは任意の空白です。ここまでの形式に従って、例えば次の様に記述します。

/**
 * 緯度経度を平面座標（測地座標）に変換
 * @link http://landhere.jp/docs/gis_phplib.html 引用元：地理情報関連 PHPライブラリ - LANDHER
 * @link https://vldb.gsi.go.jp/sokuchi/surveycalc/surveycalc/algorithm/bl2xy/bl2xy.htm 検証元：平面直角座標への換算　計算式
 *
 * @param int $K 19座標系の系番号
 * @param float $Lp 経度の度点
 * @param float $bp 緯度の度点
 * @return float[] array形式のXY座標
 */

　詳しい記述できるタグ、型は冒頭のリファレンスにあります。