萬盛學電腦網

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

PHPDocumentor 代碼註釋規範完整指南:標籤體系、最佳實踐與自動化文檔生成

PHPDocumentor (phpDocumentor) 簡介

phpDocumentor 是 PHP 專案**標準化 API 文檔生成工具**,從原始碼的 DocBlock 註釋提取結構化資訊,生成 HTML/PDF/CHM 等格式文檔。現代版本 (v3+) 支援 PHP 8.1+、屬性、聯集型別、泛型等新特性。

安裝與使用

# Composer 安裝 (專案級)
composer require --dev phpdocumentor/phpdocumentor

# 或全域安裝
composer global require phpdocumentor/phpdocumentor

# 生成文檔
vendor/bin/phpdoc -d src -t docs/api --template=clean

# 或使用配置檔 phpdoc.xml
vendor/bin/phpdoc -c phpdoc.xml

DocBlock 結構規範

<?php
/**
 * 這是摘要描述 (Summary) - 單行,以點號結束,會顯示在列表中。
 *
 * 這是詳細描述 - 可跨多行,支援 Markdown 語法,
 * 詳細說明功能、演算法、副作用、使用範例等。
 *
 * @param string $name 用戶名稱
 * @param int    $age  年齡,必須大於 0
 * @return bool 成功返回 true
 * @throws InvalidArgumentException 年齡小於等於 0 時拋出
 * @see UserRepository::findByName() 相關查詢方法
 * @since 2.1.0
 * @deprecated 3.0 將移除,請改用 UserService::register()
 */
function createUser(string $name, int $age): bool {
    // ...
}
?>

核心標籤完整參考表

標籤用途適用對象範例
@param參數說明function, method@param int $id 用戶 ID
@return回傳值說明function, method@return User|null 找不到回傳 null
@var屬性/變數型別property, variable@var string[] $tags 標籤列表
@property魔術屬性class@property string $fullName 完整姓名
@method魔術方法class@method User find(int $id)
@throws拋出異常function, method@throws NotFoundException 找不到
@see參考連結所有@see https://example.com/docs
@since起始版本所有@since 1.5.0
@deprecated棄用說明所有@deprecated 2.0 Use newMethod()
@author作者資訊file, class@author Name <email@example.com>
@copyright版權聲明file, class@copyright 2024 Company Inc.
@license授權條款file, class@license MIT
@package邏輯分組file, class@package App\Services
@subpackage子分組class@subpackage Authentication
@uses使用關係function, method@uses Cache::get() 使用快取
@internal內部說明(不輸出文檔)所有@internal 暫時硬編碼,待重構
@inheritdoc繼承父類文檔method, property@inheritdoc
@mixinTrait 混入class@mixin TimestampableTrait
@template泛型參數class, method@template T of EntityInterface
@psalm-*/@phpstan-*靜態分析輔助所有@psalm-suppress MixedAssignment

型別表示規範 (PSR-5 / phpDocumentor 標準)

<?php
// 基礎型別
@param int $id
@param string $name
@param bool $active
@param float $price
@param array $tags
@param callable $callback
@param resource $handle
@param object $entity
@param iterable $items
@param mixed $data

// 類/介面型別
@param User $user
@param \App\DTO\UserDTO $dto
@param DateTimeInterface $createdAt

// 陣列詳細型別
@param string[] $names           // 索引陣列
@param array $names // PHP 8.1+ / Psalm/PHPStan 語法
@param array $usersByEmail // 關聯陣列

// 可為 null
@param string|null $nickname
@param ?string $nickname         // PHP 8.0+ 簡寫

// 聯集型別
@param string|int $id
@param User|Admin|Guest $actor

// 可呼叫型別
@param callable(string): bool $filter
@param Closure(User): User $transformer

// 物件形狀 (PHPStan/Psalm)
@param array{id: int, name: string, email?: string} $data

// 泛型
@template T
@param T $value
@return T

檔案級、類級、方法級 DocBlock 範例

檔案級

<?php
/**
 * 用戶服務層
 *
 * 處理用戶註冊、認證、資料更新等核心業務邏輯。
 * 整合 UserRepository、EventDispatcher、CacheManager。
 *
 * @package App\Services
 * @subpackage User
 * @author 張三 <zhang@example.com>
 * @copyright 2024 Example Corp.
 * @license MIT
 * @since 2.0.0
 */
declare(strict_types=1);

namespace App\Services;
?>

類級

<?php
/**
 * 用戶服務
 *
 * 提供用戶生命週期管理功能。
 * 
 * @property-read UserRepository $repository 僅供內部使用
 * @method User findByEmail(string $email) 動態查找方法
 * @implements UserServiceInterface
 */
class UserService implements UserServiceInterface {
    /** @var UserRepository */
    private $repository;
    
    /** @var EventDispatcherInterface */
    private $dispatcher;
    
    /** @var CacheInterface */
    private $cache;
    
    /**
     * 建構子
     *
     * @param UserRepository $repository
     * @param EventDispatcherInterface $dispatcher
     * @param CacheInterface $cache
     */
    public function __construct(
        UserRepository $repository,
        EventDispatcherInterface $dispatcher,
        CacheInterface $cache
    ) {
        $this->repository = $repository;
        $this->dispatcher = $dispatcher;
        $this->cache = $cache;
    }

方法級

<?php
    /**
     * 註冊新用戶
     *
     * 執行流程:
     * 1. 驗證郵箱唯一性
     * 2. 雜湊密碼
     * 3. 建立用戶實體
     * 4. 發送歡迎郵件 (非同步)
     * 5. 觸發 UserRegistered 事件
     *
     * @param string $email 郵箱地址 (唯一)
     * @param string $password 明文密碼 (最少 8 字元)
     * @param string $name 顯示名稱
     * @param array $attributes 額外屬性 (可選)
     * @return User 新建立的用戶實體
     * @throws ValidationException 參數驗證失敗
     * @throws ConflictException 郵箱已存在
     * @see UserRepository::create()
     * @see UserRegistered
     * @since 2.1.0 新增 $attributes 參數
     */
    public function register(
        string $email,
        string $password,
        string $name,
        array $attributes = []
    ): User {
        // 實現...
    }

現代化工具鏈整合

1. IDE 支援 (PhpStorm, VS Code + PHP Intelephense)

  • 即時型別檢查、自動完成、重構支援
  • DocBlock 自動生成 (`/**` + Enter)
  • 標記 `@phpstan-*`、`@psalm-*` 整合靜態分析

2. 靜態分析工具

# PHPStan (推薦)
composer require --dev phpstan/phpstan
vendor/bin/phpstan analyse src --level=5

# Psalm
composer require --dev vimeo/psalm
vendor/bin/psalm --src=src

# 整合 CI
# .github/workflows/static-analysis.yml

3. 文檔自動化部署

# GitHub Actions 範例
# .github/workflows/docs.yml
name: Generate API Docs
on:
  push:
    branches: [main]
    tags: ['v*']
jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: shivammathur/setup-php@v2
        with: {php-version: '8.2'}
      - run: composer install --no-interaction
      - run: vendor/bin/phpdoc -c phpdoc.xml
      - uses: peaceiris/actions-gh-pages@v3
        if: github.ref == 'refs/heads/main'
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: docs/api

註釋品質檢查清單

檢查項標準工具支援
公共 API 100% 覆蓋所有 public/protected 類、方法、屬性有 DocBlockPHPStan `checkMissingIterableValueType` 等
型別宣告一致性PHP 8 類型宣告與 @param/@return/@var 一致PHPStan, Psalm, Rector
無 @param 未使用參數所有 @param 對應實際參數phpDocumentor 驗證
無 @return 缺失非 void 方法必須有 @returnPHPStan `checkMissingReturnType`
描述清晰度摘要 < 80 字,說明「做什麼」而非「怎麼做」Code Review
範例可執行@example 或說明中的代碼可直接運行Doctest (實驗性)

總結

優質的 DocBlock 註釋是**程式碼文檔化、IDE 智能提示、靜態分析、自動化文檔生成**的基石。核心原則:

  1. 與程式碼同步維護:重構時同步更新註釋
  2. 型別優先:PHP 8 原生型別宣告為主,DocBlock 型別補充泛型/陣列形狀等無法原生表達的資訊
  3. 面向使用者:寫給「呼叫者」看,說明契約、副作用、例外、範例
  4. 工具化驗證:CI 整合 phpDocumentor、PHPStan、Psalm 確保品質
copyright © 萬盛學電腦網 all rights reserved