注册 登录  
 加关注
   显示下一条  |  关闭
温馨提示!由于新浪微博认证机制调整,您的新浪微博帐号绑定已过期,请重新绑定!立即重新绑定新浪微博》  |  关闭

php开发lamp

《西安--木木》-经历丰富了生活。 架构师QQ群: 246695517

 
 
 

日志

 
 

使用PhpDocumentor生成文档--类型注释的用法  

2014-10-24 10:04:34|  分类: php基础 |  标签: |举报 |字号 订阅

  下载LOFTER 我的照片书  |
     
使用PhpDocumentor生成文档--类型注释的用法 -  灵听溪水  - php开发lamp-王伟
好的搭配,好比一篇好的文档。(木木*题记)

       我们开发的所有类都会使用PHPDoc风格的注释,这样就能很容易地为所有类构建API文档。PHPDoc建立在Sun公司的Javadoc系统基础之 上,这是一种为所有函数、参数、变量和包加注释的简单方法,以便于开发人员轻松地重用这些函数、参数、变量和包。

  尽管这一点对于这个Web应用的开发并不太重要,但开发过程中使用这种风格的注释是一个好习惯。另外,查看本书中的代码示例时你会发现,每个函数前面有一个PHPDoc注释块确实很有用。

  注解

  本书中列出的代码通常不包含PHPDoc注释,因为在正文中会对这些代码做详细的解释和说明。不过,这个Web应用的下载代码中会尽可能包含PHPDoc注释。

  PHPDoc的做法是在每个函数、类或变量定义前放置一个注释块。并不是所有情况下都要求如此,只是在必要的情况下才这么做。

  每个注释块最前面是一个描述,然后是一个或多个可选的参数。例如,向一个函数增加PHPDoc注释时,可以指定输入参数和返回值数据。显然,为变量定义所编写的PHPDoc注释则包含不同的信息。

  以下代码显示了为一个简单的用户自定义函数编写PHPDoc注释的例子:


  首先要注意注释块如何开始。/**指示PHPDoc解析器一个PHPDoc注释已经开始。

  注释块的第一行是一个短的描述。我个人的喜好是在此只写函数、类或变量的名。

  注释块中下一部分是一个比较长的描述。在这里我会尽力以一种黑盒的观点描述函数、类或变量的作用。也就是说,它会做什么,而不是它怎样做。所有具体的功能或繁杂的逻辑都由代码中的标准注释来解释。

  注解

  尽管不是必需的,不过通常的约定是在/** … */块每行起始处包含一个星号。这主要是为了提高可读性,还能容易地发现整个PHPDoc块。

  注释块中最后一部分包含各个PHPDoc参数,解析器用这些参数来更好地链接API文档,从而为你提供实用的文档。每个参数最前面是一个@,后面紧跟着参数名,然后是该参数所需的信息。

   这个例子中可以看到@param和@return参数。@param用于指定函数参数的各个方面:首先是参数的类型(在这里,第一个参数是一个字符 串);接下来是参数名(这里是$name);最后是一个简短的描述,说明输入的数据应当包含哪些内容。@return参数用于提供函数所返回数据的有关信 息:先指定数据的类型,然后是返回数据所包含内容的一个简短描述。

 

 

使用技巧:
      先敲出字符串 /**, 再按下回车键Enter, 即可自动生成如下注释结构:

        /**

          *

          */

 

 

+++++++++++++++++++++++++++++++++++++++++++++

 
常用PHPDoc属性

 

复制代码
/**
 * @name 名字
 * @abstract 申明变量/类/方法
 * @access 指明这个变量、类、函数/方法的存取权限
 * @author 函数作者的名字和邮箱地址
 * @category 组织packages
 * @copyright 指明版权信息
 * @const 指明常量
 * @deprecate 指明不推荐或者是废弃的信息
 * @example 示例
 * @exclude 指明当前的注释将不进行分析,不出现在文挡中
 * @final 指明这是一个最终的类、方法、属性,禁止派生、修改。
 * @global 指明在此函数中引用的全局变量
 * @include 指明包含的文件的信息
 * @link 定义在线连接
 * @module 定义归属的模块信息
 * @modulegroup 定义归属的模块组
 * @package 定义归属的包的信息
 * @param 定义函数或者方法的参数信息
 * @return 定义函数或者方法的返回信息
 * @see 定义需要参考的函数、变量,并加入相应的超级连接。
 * @since 指明该api函数或者方法是从哪个版本开始引入的
 * @static 指明变量、类、函数是静态的。
 * @throws 指明此函数可能抛出的错误异常,极其发生的情况
 * @todo 指明应该改进或没有实现的地方
 * @var 定义说明变量/属性。
 * @version 定义版本信息
 */
复制代码
  评论这张
 
阅读(381)| 评论(0)
推荐 转载

历史上的今天

在LOFTER的更多文章

评论

<#--最新日志,群博日志--> <#--推荐日志--> <#--引用记录--> <#--博主推荐--> <#--随机阅读--> <#--首页推荐--> <#--历史上的今天--> <#--被推荐日志--> <#--上一篇,下一篇--> <#-- 热度 --> <#-- 网易新闻广告 --> <#--右边模块结构--> <#--评论模块结构--> <#--引用模块结构--> <#--博主发起的投票-->
 
 
 
 
 
 
 
 
 
 
 
 
 
 

页脚

网易公司版权所有 ©1997-2017