PHPDoc常见注释标签说明

2019-03-07   阅读:768   分类:后端    标签: 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
抽象类的变量和方法
@accesspublic,private or protected文档的访问权限和使用权限。@access private表明这个文档是私有的
@author简忆blogs<2938039696@qq.com>文档作者信息
@copyright名称  时间文档版权信息
@deprecatedVersion文档中被废除的方法
@deprec
同@deprecated
@example/path/to/example文档的外部保存示例文件的位置
@exception
文档中方法抛出的异常,也可参照@throws
@global类型:$globalvarname文档中全局变量及有关的方法和函数


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


【腾讯云】11.11 云上盛惠,云产品限时抢购,1核2G云服务器首年88元

‘简忆博客’微信公众号 扫码关注‘简忆博客’微信公众号,获取最新文章动态
转载:请说明文章出处“来源简忆博客”。http://www.tpxhm.com/adetail/109.html

×
觉得文章有用就打赏一下文章作者
微信扫一扫打赏 微信扫一扫打赏
支付宝扫一扫打赏 支付宝扫一扫打赏

文章评论(0)

登录
头像

简忆博客
仕而优则学,学而优则仕。

置顶推荐

打赏本站

如果你觉得本站很棒,可以通过扫码支付打赏哦!
微信扫码:你说多少就多少~
微信扫码
支付宝扫码:你说多少就多少~
支付宝扫码
×