artisanコマンドでファイルを自動生成すると、コメントアウトで@paramや@returnが記載されていることがある。この意味について。

目次

1. 実例
2. PHPDoc
3. 冒頭のアットマークの意味
4. タグの書き方
5. タグの種類

実例

例えば、php artisan make:middleware ミドルウェア名でミドルウェアを作成した場合、以下のようなファイルが自動生成される。

<?php

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class test
{
    /**
     * Handle an incoming request.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Closure  $next
     * @return mixed
     */
    public function handle(Request $request, Closure $next)
    {
        return $next($request);
    }
}

このコメントアウトの部分。

PHPDoc

これは関数の説明を一定のルールに沿って記述したもの。

このルールをPHPDocs、コメントアウトで囲まれた人まとまりの説明文をDocブロックと呼ぶ。

Docブロックの書き方

/**
  * 説明の要約
  *
  * 説明の詳細（複数行）
  *
  * 要素（タグ）の説明
  *  
  */

＞PHPDocリファレンス

冒頭のアットマークの意味

@paramのように冒頭が@で始まる文字列をタグと呼ぶ。
タグづけすることで明示的にして説明をわかりやすくしている。

各タグの書き方と種類

タグの書き方

タグの説明文の書き方の基本形は下記となる。

・@タグ名 [型/クラス] [名前/変数名] [説明文]

タグ名と型のみ記述されていたり、説明文が無かったりなど、記述はまちまち。

//クラスと変数
* @param  \Illuminate\Http\Request  $request

//型のみ
* @return mixed

タグの種類

よく使われているタグ

タグ	内容	実例
@param	引数のデータ（１個）	* @param \Closure $next
@return	関数やメソッドの戻り値。	* @return mixed
@version	バージョン情報	* @version 1.0.1
@method	使用されているマジックメソッド	* @method setString(integer $integer)
@author	作成者情報	* @author My Name <[e-mail]>

タグ一覧

かなりの量のタグが用意されている。
PHPDocタグ一覧