PHP PHPDoc 注释标记及编写规范详解

核心功能标记

这些标记用于定义代码的基本属性、访问控制和版本信息：

• @access：指定关键字（类、函数、变量）的存取权限，如 private、public 或 protected。
• @author：指明代码的作者。
• @copyright：声明版权信息。
• @version：标识当前文件或方法的版本号。
• @license：指定开源协议，通常紧跟 URL 和显示名称，例如 @license MIT。

类与方法控制标记

用于描述类的结构、状态及其对继承的影响：

• @static：指明该元素为静态成员。
• @final：表示该类、方法或属性被标记为 final，禁止被派生或修改。
• @abstract：说明当前类是一个抽象类。
• @deprecated：标记已废弃的代码元素，提醒后续开发者慎用或迁移。
• @package：将多个元素在逻辑上归组到一个包或命名空间中。

输入输出与异常处理标记

这是函数文档中最关键的交互部分，直接影响自动化工具的准确性：

• @var：明确变量的数据类型，如 int、string、bool 等。
• @param：详细描述函数的一个参数，需包含类型、名称和简要说明。
• @return：指明方法或函数的返回值类型。
• @throws：说明函数在执行过程中可能抛出的错误异常类型及触发条件。
• @global：标识函数内部引用的全局变量。

第1步：构建标准文档块外壳

所有 PHPDoc 注释必须以 /** 开始，以 */ 结束。每行内容应以 * 开头，确保格式符合解析器要求。

第2步：编写具体的标签描述

在文档块内部，严格按照上述标记规范填写具体内容。对于复杂的数据类型，建议使用联合类型语法（如 @param int|string $value），以提高类型描述的精确度。

内联标签与高级用法

除了常规的块级注释，PHPDoc 还支持行内内联标签，主要用于在代码文本中插入链接或源文件展示：

• {@link}：创建超链接，指向类、方法或外部文档。
• {@source}：在当前文档中直接嵌入一段函数或方法的源代码片段。
• @example：指示解析器读取指定路径的文件内容并高亮显示，常用于演示用法。
• @filesource：类似于 @example，但默认读取当前正在解析的 PHP 文件本身的内容。

编写规范与建议

为了最大化 PHPDoc 工具的效用，请遵循以下准则：

1. 完整性：函数必须通过 @param 和 @return 完整说明其输入与输出；涉及全局变量的函数需使用 @global。
2. 简洁性：描述语尽量简明扼要，优先使用短语而非长句，避免冗余信息。
3. 一致性：若同一代码元素存在重复定义，应使用 @ignore 忽略多余部分，仅保留有效文档。
4. 可读性增强：在非文档性注释中适当使用 {@link} 关联相关代码片段，或通过 @todo 标记待改进之处。
5. 变量类型标注：显式使用 @var 标注全局变量、静态变量和常量的具体类型，消除 IDE 推断歧义。

以上就是 PHPDoc 注释标记及规范的详细内容，更多关于 PHP 编码实践的资料请关注本站其它相关文章！