主题
  • 默认模式
  • 浅蓝色模式
  • 淡绿色模式
  • 深夜模式

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 内部使用
 */


评论区 0
发表评论