萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> PHP 程式設計

PHPDoc 註解標籤完整規範:標準標籤與行內標籤對照表

規範的 PHPDoc 註解能生成專業 API 文檔,支援 IDE 智能提示、靜態分析。本文整理官方標準標籤與行內標籤,並提供撰寫規範建議。

區塊標籤(Block Tags,每行開頭 @)

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

行內標籤(Inline Tags,{@...})

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

撰寫規範建議

  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) {
        // ...
    }
}
?>
copyright © 萬盛學電腦網 all rights reserved