给php代码添加规范的注释phpDocumentor

 2016-12-24 14:04

在phpdocumentor中,注释分为文档性注释和非文档性注释。所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被phpdoc分析的关键字,例如class,var等。那些没有在关键字前面或者不规范的注释就称作非文档性注释,这些注释将不会被phpdoc所分析,也不会出现在你产生的api文当中。

一些注释规范

  • 注释必须是 /** * XXXXXXX */ 的形式

  • 对于引用了全局变量的函数,必须使用glboal标记。

  • 对于变量,必须用var标记其类型(int,string,bool...)

  • 函数必须通过param和return标记指明其参数和返回值

  • 对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可

  • 调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。

  • 必要的地方使用非文档性注释,提高代码易读性。

  • 描述性内容尽量简明扼要,尽可能使用短语而非句子。

  • 全局变量,静态变量和常量必须用相应标记说明

<!--?php
/**
* @name 名字
* @abstract 申明变量/类/方法
* @access 指明这个变量、类、函数/方法的存取权限
* @author 函数作者的名字和邮箱地址
* @category  组织packages
* @copyright 指明版权信息
* @const 指明常量
* @deprecate 指明不推荐或者是废弃的信息MyEclipse编码设置
* @example 示例
* @exclude 指明当前的注释将不进行分析,不出现在文挡中
* @final 指明这是一个最终的类、方法、属性,禁止派生、修改。
* @global 指明在此函数中引用的全局变量
* @include 指明包含的文件的信息
* @link 定义在线连接
* @module 定义归属的模块信息
* @modulegroup 定义归属的模块组
* @package 定义归属的包的信息
* @param 定义函数或者方法的参数信息
* @return 定义函数或者方法的返回信息
* @see 定义需要参考的函数、变量,并加入相应的超级连接。
* @since 指明该api函数或者方法是从哪个版本开始引入的
* @static 指明变量、类、函数是静态的。
* @throws 指明此函数可能抛出的错误异常,极其发生的情况
* @todo 指明应该改进或没有实现的地方
* @var 定义说明变量/属性。
* @version 定义版本信息
*/
function XXX($a){..}
-->
<!--?php
/**
* Sample File 2, phpDocumentor Quickstart
*
* This file demonstrates the rich information that can be included in
* in-code documentation through DocBlocks and tags.
* @author Greg Beaver <cellog@php.net-->
* @version 1.0
* @package sample
*/
  
//PHP code
  
/**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional') {
    static $staticvar = 7;
    global $_myvar;
    return $staticvar;
}



文章来自:http://www.cnblogs.com/dhsx/p/4969345.html

作者头像

作者:紫铜炉

自由博主,网页设计师。我关注科技产品和个人博客发展,注重用户体验和界面优化。

 发表评论: