PHPDoc常见注释标签说明

2019-03-07 阅读：3044 分类：后端标签： PHP

良好的只是习惯，不仅可以让别人更容易读懂你的代码，也避免出现“这是我写的代码么？”这样的疑问。代码注释的分格因人而异，但只要结构合理、通俗易懂可满足要求。

除了开发团队编码规范要求外，注释一般可分为文件注释、类注释和方法注释3种。这里参考PHPDoc的注释规范，他是一种注释PHP的代码的正式标准，在IDE中提供代码完成、类型提示和除错功能，而且支持面向对象和面向过程的不同代码分分格。

下面是一个典型的带有PHP注释的用户类（User）:

<?php
/**
 * 用户类‘
 * @category PHP
 * @author   dz5362<2938039696@qq.com>
 * @version Release：1.1
 */
 class User{
  /**
   * 用户名
   *
   * @var( string)
   */
  private $user = "";
  /**
   * 用户类构造方法
   */
  public function __contruct(){

  }
  /**
   * 获取用户名
   *
   * @return string
   * 
   */
  public function getUsername(){
  	return $this->username;
  }
  /**
   * 设置用户名
   *
   * @param string $username 用户名1
   * @return mixed
   */
  public function setUserName($username=''){
  	return $this->username = $username;
  }
 }

?>

从实例中可以看出，无论是类注释，还是方法注释，都使用了类似“@标签名说明内容”的方式，对注释进行描述，多个标签描述组成了注释块。而这样的标签还有很多，开发者使用的时候可以灵活搭配。PHPDoc提供的常见注释标签说明如下：

PHPDoc提供的常见注释标签说明

标签	实例	说明
@abstract		抽象类的变量和方法
@access	public，private or protected	文档的访问权限和使用权限。@access private表明这个文档是私有的
@author	简忆blogs<2938039696@qq.com>	文档作者信息
@copyright	名称时间	文档版权信息
@deprecated	Version	文档中被废除的方法
@deprec		同@deprecated
@example	/path/to/example	文档的外部保存示例文件的位置
@exception		文档中方法抛出的异常，也可参照@throws
@global	类型：$globalvarname	文档中全局变量及有关的方法和函数

@ignore		忽略文档中指定的关键词
@internal		开发团队内部信息
@link	URL	雷士listense,但还可以通过访问link地址找到文档更多的详细信息
@name	变量别名	为某个变量指定别名
@magic		PHPDoc兼容phpDocument的标签
@package	封装包的名称	一组相关类、函数封装的包名称
@param	如 [$username] 用户名	输入变量含义注释
@return	如返回bool	输出函数返回结果描述。一般不用void（空返回结果）的函数中
@see	如Class Login()	文件关联的任何元素（全局变量，包括页面、类、函数、定义、方法、变量）
@since	version	记录什么时候对文档的哪些部分进行了修改

@static		记录静态类方法
@staticvar		在类、函数中使用的静态变量
@subpackage		子版本
@throws		抛出的异常
@todo		表示文件未完成或者要完善的地方