phpDocumentor教程：深入理解DocBlock文档块-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00045/article/details/148548502

phpDocumentor教程：深入理解DocBlock文档块

phpDocumentor Documentation Generator for PHP 项目地址: https://gitcode.com/gh_mirrors/ph/phpDocumentor

什么是DocBlock？

DocBlock是源代码中的一种特殊注释格式，用于为类、方法或其他结构元素提供详细的文档说明。作为phpDocumentor项目的核心概念，DocBlock不仅帮助开发者理解代码功能，还能自动生成专业的技术文档。

DocBlock能做什么？

在PHP开发中，我们可以使用DocBlock为以下结构元素添加文档：

函数(function)
常量(constant)
类(class)
接口(interface)
特性(trait)
类常量(class constant)
属性(property)
方法(method)

此外，虽然PHP本身不将文件视为语言结构，但PHPDoc标准也支持为文件和include/require语句添加DocBlock文档。

DocBlock的基本结构

一个标准的DocBlock由三部分组成：

摘要(Summary)：简要描述元素的功能
详细描述(Description)：提供更深入的说明
标签(Tags)：使用@符号标记的元信息

/**
 * 计算两个数的和（摘要）
 *
 * 这个方法接收两个数字参数，返回它们的和。
 * 支持整数和浮点数运算。（详细描述）
 *
 * @param int|float $a 第一个操作数
 * @param int|float $b 第二个操作数
 * @return int|float 两个参数的和
 */
function add($a, $b) {
    return $a + $b;
}

文件级DocBlock的特殊性

文件级DocBlock需要特别注意其位置：

<?php
/**
 * 这个DocBlock属于文件
 */

/**
 * 这个DocBlock属于类
 */
class MyClass {
    // 类实现
}

如果DocBlock后紧跟其他结构元素而没有空行，它将被视为该元素的文档而非文件文档。

DocBlock的语法细节

注释标记：必须以/**开头，以*/结尾
每行前缀：中间每行应以*开头
摘要结束：遇到句号加换行或空行时摘要结束
描述结束：遇到标签或DocBlock结束时描述终止

标签系统详解

phpDocumentor支持丰富的标签系统，常见标签包括：

@param：描述参数类型和用途
@return：描述返回值
@throws：描述可能抛出的异常
@var：描述类属性的类型
@deprecated：标记已弃用的元素

/**
 * 用户登录验证
 *
 * 验证用户提供的凭据是否匹配数据库记录
 *
 * @param string $username 用户名
 * @param string $password 密码
 * @return bool 验证成功返回true，否则false
 * @throws DatabaseException 数据库连接失败时抛出
 */
function authenticate($username, $password) {
    // 实现代码
}