PHP注释规范

对于引用了全局变量的函数，必须使用@glboal标记
对于变量，必须用@var标记其类型(int,string,bool…)
函数必须通过@param和@return标记指明其参数和返回值
调用了其他函数或类的地方，要使用@link或其他标记链接到相应的部分，便于文档的阅读。
必要的地方使用非文档性注释，提高代码易读性。
描述性内容尽量简明扼要，尽可能使用短语而非句子。
全局变量，静态变量和常量必须用相应标记说明

注释

@author 添加作者

语法 @author [name] [<email address>]

@deprecated 弃用

语法 @deprecated [<version>] [<description>]

/**
 * @deprecated 3.0 弃用此方法
 * @return string
 */
public static function invoke()
{
	$argc="asd";
	return 'Hello Guozhen';
}

@internal 只限于当前文件调用

语法:@internal [description]

@link 外部跳转链接

语法@link [URI] [<description>]

/**
 * <1>.引导外部跳转链接
 *
 * @link https://www.baidu.com
 * @return string
 */
public static function buildBaiduUrl()
{
	return 'https://www.baidu.com';
}

@see 跳转内部或外部链接

/**
 * @see Email::fromString()
 * @see https://www.baidu.com
 */

与 @link 区别

-	@see	@link
外部链接	√	√
内部程序	√	X

@method 声明哪些魔术方法可以调用

语法 @method [modifier] [return type] [name]([[type] [parameter]<, …>]) [<description>]

/**
 * @method int incr($number, $step = 1) 递增数字
 * @method array explode(string $delimiter, string $string) 分割字符串
 * @method static void incrStatic($number, $step = 1) 递增数字(静态)
 */
class TagMethod
{
	function __call($name, $arguments)
	{
	}
	
	static function __callStatic($name, $arguments)
	{
	}
}

@param 参数说明

语法 @param [Type] [name] [<description>]

变量类型	说明
string	字符串
integer/int	number/int类型
boolean/bool	false/true
float/double	number/浮点数
object	对象实例
specifiedType	指定类
mixed	任意类型
array/specifiedType[]	数组，可以指定成指定类型的数组
resource	文件资源类型
void	无返回值
null	-
callable	可执行的回调函数
function	不一定能执行的方法
self/$this	当前实例

@property[-(read|write)] 调用魔术方法get/set

语法 @property [Type] [name] [<description>] property-read 只读 property-write 只写

/**
 * @property int    $age    数字
 * @property string $name 字符串
 * @property mixed  $any       任意类型返回值
 */
class TagProperty
{
	public function __get($name)
	{
	}
	
	public function __set($name, $value)
	{
	}
}

$tag = new TagProperty();
// ide 会自动提示
$tag->name;

@return

语法 @return [Type] [<description>]

@throws 可能抛出的异常

语法 @throws [Type] [<description>]

/**
 * @throws RuntimeException
 * @throws InvalidArgumentException
 */

@var 变量

语法 @var [Type] [$element_name] [<description>]

/**
 * @var string  年龄
 */
protected string $age;

/** @var string $age */
$age;

@example 记录外部保存的示例文件的位置'

语法 @example [位置] [<起始行号> [<行数>] ] [<描述>]

@example demo.php 10 3 使用示例

@ignore 忽略相同 define

if ($ostest) {
     /**
      * This define will either be 'Unix' or 'Windows'
      */
     define("OS","Unix");
 } else {
     /**
      * @ignore
      */
     define("OS","Windows");
 }

@since 从什么版本开始

@since 1.0.2 添加了$b参数

@todo

语法 @todo [描述]

PHP注释规范