規範的 PHPDoc 註解是專案可維護性的基石。本文系統整理所有標準區塊標籤（@tag）與行內標籤（{@tag}），並提供撰寫規範 9 原則與標準範例。

區塊標籤完整對照表

標籤	適用範圍	說明與語法
@access	class, function, var, define, module	存取權限：public/protected/private
@author	所有	作者：Author Name <email@example.com>
@copyright	class, function, var, define, module, use	版權聲明
@deprecated	class, function, var, define, module, constant, global, include	棄用標記，建議說明替代方案
@example	所有	範例檔案路徑，文檔生成器會高亮顯示
@const	define	常數說明
@final	class, function, var	禁止繼承/覆寫/修改
@filesource	file	顯示當前檔案完整原始碼
@global	function	函數內使用的全域變數：@global type $varname
@ignore	所有	文檔生成時忽略此元素
@license	所有	授權：@license URL 名稱
@link	所有	相關連結，可連到文檔內其他元素
@name	所有	元素別名
@package	file: define,function,include / class: class,var,method	邏輯分組：@package MyProject\Component
@abstract	class	標記抽象類別
@param	function, method	參數：@param type $name 說明
@return	function, method	返回值：@return type 說明
@static	function, method, var	標記靜態成員
@var	var, property	變數/屬性型別：@var Type 說明
@version	所有	版本號：@version 1.0.0
@todo	所有	待辦事項
@throws	function, method	拋出異常：@throws ExceptionClass 條件

行內標籤

標籤	語法
{@link}	{@link URL 文字} 或 {@link 元素名稱}
{@source}	顯示函數/方法原始碼片段

撰寫規範 9 原則

1. 格式：/** 開頭，每行 * 開頭，*/ 結尾。
2. 引用全域變數必加 @global。
3. 變數/屬性必標型別（@var string、@var int[]）。
4. 函數/方法必標 @param、@return。
5. 重複元素用 @ignore 隱藏多餘。
6. 交叉引用用 @link/@see。
7. 邏輯複雜處加非文檔註解（////* */）。
8. 描述簡潔，優先片語，首行摘要 ≤ 80 字元。
9. 全域/靜態/常數必標 @global/@static/@const。

標準範例

<?php
/**
 * 用戶服務類
 *
 * @package App\Service
 * @author  John Doe <john@example.com>
 * @version 2.1.0
 */
class UserService {
    /** @var PDO 資料庫連線 */
    private $db;

    /**
     * 依 ID 取得用戶
     *
     * @param int $id 用戶 ID
     * @return array|false 用戶資料或 false
     * @throws PDOException 資料庫錯誤
     */
    public function getById(int $id) {
        // ...
    }
}
?>