Should I use the FQN in PHPDoc if I'm importing the class with use?

Question

Let's say I have a UserController class and I'm importing the App\User class with use. Inside, there is a show() method that receieves an instance of User.

namespace App\Http\Controllers;

use App\User;

class UserController extends Controller
{
    /**
     * Show user info
     * 
     * @param  User $user
     * @return Illuminate\Http\JsonResponse
     */
    public function show(User $user)
    {
        // Do something...
    }
}

Is it recommended to add the fully qualified name of User in PHPDoc even if I'm importing the class with use?

Answer 1

Use FQN if there are no use statement, as it would be recognized as a different class, in Your case as \JsonResponse which is not imported.

As for User class, use short name.

It is more convenient to import class with use statement and write short name in docblock.

Also class aliases can be used, for instance:

namespace App\Http\Controllers;

use App\User;
use Illuminate\Http\JsonResponse as Response;

class UserController extends Controller
{
    /**
     * Show user info
     * 
     * @param  User $user
     * @return Response
     */
    public function show(User $user)
    {
        // Do something...
    }

}