讨论一下怎么给方法写注释

[coo]

一直有个困惑，想了好几天了。

蛮常见的一个场景，假定有如下方法（是 Laravel 的）：

class MyController extends BaseController
{
    public function detail(Request $request)
    {
        $id = $request->input('id');

        return Detail::find($id);
    }
}

访问这个方法的路径是：/my/detail?id=1

ID 参数因为是 Query 参数无法通过路由指定到函数参数中，那么我应该怎么给 ID 参数写注释？

和 $request 一起写在上面的注释块中：

/**
 * 返回指定 ID 的详细信息
 * @param Request $request
 * @param Integer $id
 * @return \Illuminate\Http\JsonResponse
 **/

还是在代码中：

// Detail ID
$id = $request->input('id');

对于这样的代码注释大家是怎么写的？

[jarlyyn]

phpdoc.

另外，第 2 种方法有啥意义？不如直接
$detailID=$request->input('id');

[coo]

@jarlyyn 有的时候有数个 ID 这样的参数，不能全部通过变量名称体现出来意义，需要一些解释。