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

PHP 文件註解標籤與規範完整手冊（PHPDoc 相容）

編輯：PHP 綜合知識

標準文件區塊格式

所有文件註解必須採用 DocBlock 格式：

/**
 * 簡短描述
 *
 * 詳細說明可跨多行，
 * 可包含標籤。
 */

每行開頭以 * 對齊，標籤以 @ 開頭。

常用標籤完整對照表

標籤	適用範圍	說明	範例
@access	class, function, var, define, module	存取權限：private、public、protected	@access public
@author	所有	作者姓名/信箱	@author John Doe <john@example.com>
@copyright	class, function, var, define, module, use	版權聲明	@copyright 2024 MyCompany
@deprecated	class, function, var, define, module, constant, global, include	標記棄用，建議替代方案	@deprecated 2.0 使用 newMethod()
@example	所有	引用外部範例檔，PHPDoc 會高亮顯示	@example /path/to/example.php
@const	define	說明常數	@const int MAX_RETRY 3
@final	class, function, var	禁止繼承/覆寫/修改	@final
@filesource	所有	直接顯示當前檔案原始碼	@filesource
@global	function	函數內引用的全域變數	@global array $config
@ignore	所有	文件產生時忽略此元素	@ignore
@license	所有	授權連結與名稱	@license https://opensource.org/licenses/MIT MIT
@link	所有	相關連結（可指向文件內其他元素）	@link https://example.com/api
@name	所有	為元素指定別名	@name RealClassName
@package	page-level: define, function, include class-level: class, var, methods	邏輯分組	@package MyProject\Core
@abstract	class	標記抽象類別	@abstract
@param	function, method	參數說明：型別名稱描述	@param string $name 使用者名稱
@return	function, method	回傳值：型別描述	@return bool 是否成功
@static	function, var	標記靜態成員	@static
@var	var, property	變數/屬性型別	@var string
@version	所有	版本號	@version 1.2.3
@todo	所有	待辦事項	@todo 加入快取機制
@throws	function, method	可能拋出的例外與條件	@throws InvalidArgumentException 參數無效

Inline 標籤（{@...}）

標籤	用途
{@link}	行內連結，用法同 @link
{@source}	顯示函數/方法原始碼片段

團隊協作規範（必遵守）

格式統一：一律使用 /** ... */，禁止單行 // 或 /* */ 當文件註解。
全域變數必標 @global：函數內引用 $GLOBALS 或 global $x 時必須標註。
變數必標 @var：包含型別（int, string, bool, array, ClassName）。
函數必標 @param @return：缺一不可。
重複元素用 @ignore：同一專案出現多次（如多檔案定義相同常數）只保留一份文件。
跨檔引用用 @link：方便文件閱讀跳轉。
非文件性註解：邏輯複雜處加上 // 或 /* */ 提升可讀性。
描述簡潔：優先用片語，非完整句子。
全域/靜態/常數必標對應標籤：@global, @static, @const。

完整範例

<?php
/**
 * 使用者服務類別
 *
 * 處理使用者註冊、登入、資料更新等核心業務邏輯。
 *
 * @package    App\Services
 * @author     Jane Chen <jane@example.com>
 * @copyright  2024 MyCompany
 * @version    2.1.0
 */
class UserService
{
    /**
     * @var PDO 資料庫連線物件
     */
    private $db;

    /**
     * 建構子
     *
     * @param PDO $pdo 已連線的 PDO 實例
     */
    public function __construct(PDO $pdo)
    {
        $this->db = $pdo;
    }

    /**
     * 註冊新使用者
     *
     * @param string $email    信箱，唯一鍵
     * @param string $password 明文密碼，將自動雜湊
     * @param string $name     暱稱
     * @return int             新使用者 ID
     * @throws InvalidArgumentException 信箱格式錯誤或已存在
     */
    public function register(string $email, string $password, string $name): int
    {
        // 實作略
    }
}
?>