您现在的位置：程式碼之家 >> 編程語言 > >> 網頁程式設計 >> PHP 程式設計 >> PHP 相關知識

PHP 文件註解標籤完整規範：PHPDoc 標準與團隊協作最佳實務

編輯：PHP 相關知識

前言

統一的文件註解規範能大幅提升程式碼可讀性、維護性，並支援 IDE 智能提示、自動產生 API 文件。本文整理 PHPDoc 標準標籤、行內標籤、註解格式規範與團隊落地建議。

區塊標籤完整對照表

標籤	適用範圍	說明	範例
@access	class, function, var, define, module	存取層級	@access public
@author	所有	作者資訊	@author John Doe <john@example.com>
@copyright	class, function, var, define, module, use	版權聲明	@copyright 2024 Company Inc.
@deprecated	class, function, var, define, module, constant, global, include	標記棄用，建議替代方案	@deprecated 2.0 使用 newMethod()
@example	所有	範例檔案路徑（高亮顯示）	@example /path/to/example.php
@const	define	常量定義	@const int MAX_SIZE
@final	class, function, var	禁止繼承/覆寫	@final
@filesource	所有	顯示當前檔案完整原始碼	@filesource
@global	function	函式內引用的全域變數	@global array $config
@ignore	所有	忽略此元素不產生文件	@ignore
@license	所有	授權連結	@license MIT https://opensource.org/licenses/MIT
@link	所有	相關連結（可連結到其他文件元素）	@link https://example.com @link ClassName::method()
@name	所有	別名	@name RealClassName
@package	page: define, function, include; class: class, var, method	邏輯分組	@package App\Modules\User
@abstract	class	抽象類別	@abstract
@param	function, method	參數說明：型別名稱說明	@param string $name 使用者名稱
@return	function, method	回傳值：型別說明	@return bool 成功為 true
@static	所有	靜態成員	@static
@var	property, variable	變數型別	@var string\|null
@version	所有	版本號	@version 1.2.3
@todo	所有	待辦事項	@todo 優化查詢效能
@throws	function, method	拋出的例外類別與條件	@throws InvalidArgumentException ID 不存在

行內標籤

標籤	用法	範例
{@link}	同 @link，用於段落內	參考 {@link https://example.com 官網}
{@source}	顯示函式/方法原始碼片段	{@source}

註解格式規範（強制）

/**
 * 簡短描述（單行）
 *
 * 詳細描述（可多行，支援 Markdown）
 *
 * @param string $param1 參數說明
 * @param int    $param2 參數說明
 * @return bool  回傳說明
 * @throws Exception 條件說明
 */
function example(string $param1, int $param2): bool { ... }

關鍵規則

以 /** 開頭，*/ 結尾，每行以 * 開頭對齊。
第一行為簡短摘要，空行後為詳細說明。
@param、@return、@throws 函式/方法必寫。
變數/屬性必標 @var 型別。
引用全域變數必標 @global。
重複元素用 @ignore 隱藏多餘項。
相關元素用 @link 互連，便於文件導航。
描述簡慜明，優先用片語而非完整句子。
全域常數、靜態變數必標對應標籤。

實戰範例：完整類別註解

<?php
/**
 * 用戶服務類別
 *
 * 處理用戶註冊、認證、資料更新等核心業務邏輯。
 *
 * @package App\Services
 * @author  Jane Chen <jane@company.com>
 * @version 2.1.0
 * @since   1.0.0
 */
class UserService
{
    /**
     * @var UserRepository 用戶資料存取庫
     */
    protected $repository;

    /**
     * 建構式
     *
     * @param UserRepository $repo 注入的 Repository 實例
     */
    public function __construct(UserRepository $repo)
    {
        $this->repository = $repo;
    }

    /**
     * 依 ID 取得用戶資料
     *
     * @param int $id 用戶 ID
     * @return User|null 找到回傳 Entity，否則 null
     * @throws RepositoryException 資料層異常
     */
    public function findById(int $id): ?User
    {
        return $this->repository->find($id);
    }
}