如何为失败返回布尔值、成功返回类数组内容的PHP类方法编写PHPDocumentor注释

刚好处理过不少这种“成功返回数据、失败返回false”的PHP方法注释，给你捋清楚怎么写才规范：

首先，PHPDoc支持用联合类型来标注这种多返回值的情况，核心是在@return标签里用竖线|分隔不同的返回类型，同时必须清晰说明每种类型对应的触发场景。

针对你给出的代码（成功返回查询语句对象、失败返回false），完整的注释应该是这样：

/**
 * 获取服务器列表的查询结果对象
 *
 * 执行查询服务器数据的SQL语句，成功时返回执行后的查询对象，失败时返回布尔值false
 *
 * @return false|\PDOStatement 当SQL执行失败时返回false；成功时返回包含服务器数据的PDOStatement对象
 */
public function getServers() {
    $q = $this->db->query('SELECT * FROM servers');
    if($q->execute()) {
        return $q;
    } else {
        return false;
    }
}

如果你实际想返回的是数组格式的服务器数据（比如调用fetchAll()之后的结果，也就是你说的“类似数组”），那注释要对应调整，同时优化代码的返回值，示例如下：

/**
 * 获取所有服务器的列表数据
 *
 * 执行SQL查询并获取所有服务器的详细信息，成功时返回服务器数据数组，失败时返回布尔值false
 *
 * @return false|array<int, array<string, mixed>> 当查询执行失败时返回false；成功时返回二维数组，每个元素为单台服务器的键值对数据
 */
public function getServers() {
    $q = $this->db->query('SELECT * FROM servers');
    if($q->execute()) {
        // 返回关联数组格式的所有数据
        return $q->fetchAll(PDO::FETCH_ASSOC);
    } else {
        return false;
    }
}

这里还有几个小细节要注意：

• 类型标注要尽可能精确：比如用\PDOStatement而不是模糊的object，用array<int, array<string, mixed>>来明确数组的结构（索引数组，每个元素是关联数组）
• 注释描述要清晰：既要说明方法的核心功能，也要明确两种返回值的触发条件，让调用你的方法的开发者一眼就懂
• 如果你的数据库操作类不是PDO，那把\PDOStatement换成对应的查询对象类名就行

内容的提问来源于stack exchange，提问作者Intel