PHP 代码注释与文档生成

PHPDoc 是为 PHP 代码编写注释的一项非正式行业标准。

它提供了非常多不同的可用标签 (tags)。你可以在 PHPDoc 官方手册 中找到完整的标签列表和详细示例。良好的代码文档不仅能帮助其他开发者快速理解你的意图，还能让大多数现代代码编辑器（IDE）为你提供精准的代码自动补全和错误提示。

下面是一个基础示例，展示了你该如何为一个包含几个方法的类编写文档注释：

<?php
/**
 * @author 某某名字 <a.name@example.com>
 * @link https://docs.phpdoc.org/
 */
class DateTimeHelper
{
    /**
     * @param mixed $anything 任何可以被我们转换成 \DateTime 对象的值
     *
     * @throws \InvalidArgumentException
     *
     * @return \DateTime
     */
    public function dateTimeFromAnything($anything)
    {
        $type = gettype($anything);

        switch ($type) {
            // 一些尝试返回 \DateTime 对象的代码逻辑
        }

        throw new \InvalidArgumentException(
            "将类型为 '{$type}' 的参数转换为 DateTime 对象失败"
        );
    }

    /**
     * @param mixed $date 任何可以被我们转换成 \DateTime 对象的值
     *
     * @return void
     */
    public function printISO8601Date($date)
    {
        echo $this->dateTimeFromAnything($date)->format('c');
    }

    /**
     * @param mixed $date 任何可以被我们转换成 \DateTime 对象的值
     */
    public function printRFC2822Date($date)
    {
        echo $this->dateTimeFromAnything($date)->format('r');
    }
}

1. 注释标签结构解析

通过上面的代码示例，我们可以将文档注释拆解为以下几个核心部分来理解：

1.1 类级别注释

整个类的顶部文档包含了 @author 标签和 @link 标签。

• @author：用于记录代码的作者。如果你需要记录多位参与贡献的作者，可以在注释块中重复使用该标签。
• @link：用于提供一个网站链接，表明该网站页面与这段代码之间存在关联关系（例如关联的官方文档或业务需求说明）。

1.2 方法级别注释

在类内部，第一个方法 dateTimeFromAnything 展示了完整的参数与返回值标注：

• @param：详细记录了传递给该方法的参数类型（mixed）、参数变量名（$anything）以及一句话的参数说明。
• @return：声明了该方法成功执行后返回的数据类型（在这里会返回一个 \DateTime 对象）。
• @throws：清晰地指出了该方法在执行过程中可能抛出的所有异常类型（在这里是 \InvalidArgumentException），这能提醒调用者做好异常捕获准备。

1.3 显式 Void 与隐式省略的区别

第二个方法 (printISO8601Date) 和第三个方法 (printRFC2822Date) 在功能上非常相似，并且都像第一个方法一样包含了一个 @param 标签。

这两个方法文档注释块之间唯一的、也是最重要的区别在于是否包含 @return 标签：

• @return void：显式地明确告知我们，这个方法没有任何返回值。
• 省略标签：从历史习惯来看，直接在注释中省略 @return void 声明，同样也代表了相同的含义，即意味着该操作没有返回值。