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

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

 2016-12-24 14:04    网页设计   标签：代码   1952    发表评论

在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