PHP 注释

PHP 注释

在 PHP 中，注释用于解释代码，不会被解释器执行。PHP 支持以下几种注释方式：

---

单行注释

使用//符号来进行单行注释。

// 这是一个单行注释的例子
echo "Hello, world!"; // 这也是一个单行注释，跟在代码后面

---

Shell 风格单行注释

PHP 支持 C，C++ 和 Unix Shell 风格（Perl 风格）的注释。

# 这是一个单行注释的例子
echo "Hello, world!";  # 这也是一个单行注释，跟在代码后面

---

多行注释

使用/*和*/来包裹多行注释的内容，注释不能嵌套。

/*
这是一个
多行注释的例子
*/
echo "Hello, world!"; /* 这个注释可以跨越
                       * 多行，并且可以嵌套 */

---

文档块注释（Docblock）

这种注释通常用于文档生成工具，如 phpDocumentor。

它也是使用/** */形式，但内部通常包含特定格式的信息来描述类、方法或属性的作用。

/**
 * 计算两数之和
 * @param int $a 第一个数
 * @param int $b 第二个数
 * @return int 返回和
 */
function add($a, $b) {
    return $a + $b;
}

在 PHP 中，@ 符号通常被用作错误控制操作符，而不是注释的一部分。然而，在文档块注释（Docblock）中，@ 符号后面可以跟着一系列的标记，用来描述代码的不同方面。这些标记通常用于生成 API 文档，帮助其他开发者理解代码的作用。

---

常见的Docblock标记

✅ @param：描述函数参数

/**
 * @param int $id 用户ID
 */
function getUserById(int $id) {
    // 函数实现
}

✅ @return：描述函数返回值

/**
 * @return array 用户数据数组
 */
function getUserData(): array {
    // 函数实现
}

✅ @throws：描述函数可能抛出的异常

/**
 * @throws Exception 当发生错误时抛出
 */
function doSomething() {
    // 可能抛出异常的代码
}

✅ @var：描述变量类型

/**
 * @var string $name 用户的名字
 */
$name = "John Doe";

✅ @property：描述类属性

/**
 * @property-read int $userId 用户ID，只读属性
 */
class User {}

✅ @see：描述引用相关的类或方法

/**
 * @see User::getId 获取用户ID的方法
 */
function useUserId() {
    // 使用用户ID
}

✅ @deprecated：标记已被弃用的函数或类

/**
 * @deprecated 1.2.0 不再推荐使用此方法
 */
function oldMethod() {
    // 老的实现
}

✅ @author：描述作者信息

/**
 * @author liu <john.doe@example.com>
 */

✅ @since：标记属性或函数首次引用的版本

/**
 * @since 1.0.0 版本1.0.0
 */

✅ @version：标记代码元素的当前版本

/**
 * @version 2.0.0 版本2.0.0
 */

✅ @internal：标记为内部使用的代码元素

/**
 * @internal 内部使用
 */

---

---