【Laravel】コメントアウトの@paramや@returnとは何か？実例で解説｜PHPDocsやDocブロックの見方や使い方、タグの種類一覧

Laravelではartisanコマンドを使ってファイルを自動生成すると、そのファイルの中にコメントアウトで@parmや@returnが記載されていることがあります。

あるいは、先人たちが作成したファイルの中に、@parmや@returnが記載されていることがあります。

ここではこれらの意味や使い方を実例で解説しています。

どれのことか？

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

この中のクラスの処理の冒頭に@paramや@returnがコメントアウトで記載されています。

<?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);
    }
}

クラスの処理の中以外にも、コントローラのアクションの中の冒頭やヘルパなどにもコメントアウトで似たような記述が記載されていることがあります。

コメントアウトの@paramや@returnとは何か？

コメントアウトの@paramや@returnは、関数の説明を一定のルールに沿って記述したものです。

このルールをPHPDocsといいます（PHPドックス）。そして、コメントアウトで囲まれた人まとまりの説明文をDocブロック（ドックブロック）と呼びます。

Docブロックは大きく以下の３つで構成されています。

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

（参考）＞PHPDocリファレンス

冒頭の@（アットマーク）の意味（タグとは何か）

@paramのように冒頭が@で始まる文字列をタグと呼びます。

タグづけすることで明示的にして説明をわかりやすくしています。

タグの種類

主なタグ一覧

Docブロックで使用される主なタグには以下のようなものがあります。特に@paramや@returnは頻繁に見かけます。

タグの一覧

詳細は下記をご参考ください。

（参考）PHPDocのタグ一覧

各タグの書き方

タグの説明文の書き方の基本形は下記のようになります。

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

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

例１ クラスと変数

以下の例では、クラスと変数のみを記述しています。

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

例２ 型のみ

以下の例では、クラスと変数のみを記述しています。

* @return mixed