📚 常用 PHPDoc 標籤說明 (@ 標記)

用於撰寫 PHP 或 Laravel 程式碼註解，可被 IDE（如 PHPStorm）與文件工具（如 phpDocumentor）解析，提升程式可讀性與維護性。

✅ 函式與方法註解

標籤 說明
@return 描述方法的回傳值類型與意圖。
例：@return \Illuminate\Http\Response
@param 描述方法的參數名稱、類型與說明。
例：@param int $id 使用者 ID
@throws 說明方法中可能拋出的例外。
例：@throws \Illuminate\Database\Eloquent\ModelNotFoundException
@deprecated 標記此方法或類別已棄用，並可補充替代方式。
例：@deprecated 改用 newMethod()
@see 連結到相關類別、方法或文件。
例：@see \App\Services\UserService
@inheritdoc 自動繼承父類別或介面方法的註解內容。通常無需重複撰寫說明。

✅ 屬性與變數註解

標籤 說明
@var 說明屬性或變數的類型與用途。
例：@var \App\Models\User

✅ 其他輔助註解

標籤 說明
@link 提供與此功能相關的 URL 連結。
例：@link https://laravel.com/docs/
@example 提供實際使用範例（⚠️ 多數 IDE 不支援顯示，建議放在描述中）

🔧 建議使用範例

/**
 * 取得指定 ID 的使用者資訊
 *
 * @param int $id 使用者 ID
 * @return \Illuminate\Http\JsonResponse
 * @throws \Illuminate\Database\Eloquent\ModelNotFoundException
 * @see \App\Repositories\UserRepository::find
 */
public function show(int $id): JsonResponse
{
    // ...
}

📎 延伸閱讀