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

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

蛮常见的一个场景，假定有如下方法（是 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'); 

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