关于PHPDocument 代码注释规范的总结


Posted in PHP onJune 25, 2013

1. 安装phpDocumentor(不推荐命令行安装)
在http://manual.phpdoc.org/下载最新版本的PhpDoc
放在web服务器目录下使得通过浏览器可以访问到
点击files按钮,选择要处理的php文件或文件夹
还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
然后点击output按钮来选择生成文档的存放路径和格式.
最后点击create,phpdocumentor就会自动开始生成文档了。

2.如何写PHP规范注释
所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记,这个标记将会被当做普通内容而被忽略掉。
@access 该标记用于指明关键字的存取权限:private、public或proteced 使用范围:class,function,var,define,module
@author 指明作者
@copyright 指明版权信息
@const 使用范围:define 用来指明php中define的常量
@final 使用范围:class,function,var 指明关键字是一个最终的类、方法、属性,禁止派生、修改。
@global 指明在此函数中引用的全局变量
@name 为关键字指定一个别名。
@package 用于逻辑上将一个或几个关键字分到一组。
@abstrcut 说明当前类是一个抽象类
@param 指明一个函数的参数
@return 指明一个方法或函数的返回值
@static 指明关建字是静态的。
@var 指明变量类型
@version 指明版本信息
@todo 指明应该改进或没有实现的地方
@link 可以通过link指到文档中的任何一个关键字
@ingore 用于在文档中忽略指定的关键字

一些注释规范
a.注释必须是
/**
* XXXXXXX
*/
的形式
b.对于引用了全局变量的函数,必须使用glboal标记。
c.对于变量,必须用var标记其类型(int,string,bool...)
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可
f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。
g.必要的地方使用非文档性注释(PHPDOC无法识别的关键字前的注释),提高代码易读性。
h.描述性内容尽量简明扼要,尽可能使用短语而非句子。
i.全局变量,静态变量和常量必须用相应标记说明

能够被phpdoc识别的关键字:
Include
Require
include_once
require_once
define
function
global
class

3. 规范注释的php代码 :
<?php
/**
* 文件名(sample2.php)
*
* 功能描述(略)
*
* @author steve <https://3water.com>
* @version 1.0
* @package sample2
*/
/**
* 包含文件
*/
include_once 'sample3.php';
/**
* 声明全局变量
* @global integer $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
* 声明全局常量
*/
define('NUM', 6);
/**
* 类名
*
* 类功能描述
*
* @package sample2
* @subpackage classes(如果是父类 就添加)
*/
class myclass {
/**
* 声明普通变量
*
* @accessprivate
* @var integer|string
*/
var $firstvar = 6;
/**
* 创建构造函数 {@link $firstvar}
*/
function myclass() {
$this->firstvar = 7;
}
/**
* 定义函数
*
* 函数功能描述
*
* @global string $_myvar
* @staticvar integer $staticvar
* @param string $param1
* @param string $param2
* @return integer|string
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}
}
?>

PHP 相关文章推荐
高亮度显示php源代码
Oct 09 PHP
PHP爆绝对路径方法收集整理
Sep 17 PHP
php图片的裁剪与缩放生成符合需求的缩略图
Jan 11 PHP
PHP使用GIFEncoder类处理gif图片实例
Jul 01 PHP
PHP生成plist数据的方法
Jun 16 PHP
PHP中filter函数校验数据的方法详解
Jul 31 PHP
php简单实现短网址(短链)还原的方法(测试可用)
May 09 PHP
php实现文件预览功能
May 23 PHP
PHP实现找出有序数组中绝对值最小的数算法分析
Aug 07 PHP
PHP输出Excel PHPExcel的方法
Jul 26 PHP
解决thinkphp5未定义变量会抛出异常,页面错误,请稍后再试的问题
Oct 16 PHP
php判断某个方法是否存在函数function_exists (),method_exists()与is_callable()区别与用法解析
Apr 20 PHP
解析php中获取系统信息的方法
Jun 25 #PHP
解析PHP对现有搜索引擎的调用
Jun 25 #PHP
手把手教你打印出PDF(关于fpdf的简单应用)
Jun 25 #PHP
解析如何修改phpmyadmin中的默认登陆超时时间
Jun 25 #PHP
关于Sphinx创建全文检索的索引介绍
Jun 25 #PHP
使用Sphinx对索引进行搜索
Jun 25 #PHP
深入PHP许愿墙模块功能分析
Jun 25 #PHP
You might like
探讨php中防止SQL注入最好的方法是什么
2013/06/10 PHP
如何在JavaScript中实现私有属性的写类方式(二)
2013/12/04 Javascript
jquery实现鼠标滑过显示提示框的方法
2015/02/05 Javascript
javascript算法题:求任意一个1-9位不重复的N位数在该组合中的大小排列序号
2015/04/01 Javascript
Javascript验证Visa和MasterCard信用卡号的方法
2015/07/27 Javascript
js实现input密码框提示信息的方法(附html5实现方法)
2016/01/14 Javascript
js实现页面跳转的五种方法推荐
2016/03/10 Javascript
浅谈angularJS中的事件
2016/07/12 Javascript
详解js实现线段交点的三种算法
2016/08/09 Javascript
URL中“#” “?” &amp;“”号的作用浅析
2017/02/04 Javascript
基于BootStrap multiselect.js实现的下拉框联动效果
2017/07/28 Javascript
JS简单获取并修改input文本框内容的方法示例
2018/04/08 Javascript
微信小程序与公众号卡券/会员打通的问题
2019/07/25 Javascript
Node使用koa2实现一个简单JWT鉴权的方法
2021/01/26 Javascript
Python的Flask框架中@app.route的用法教程
2015/03/31 Python
python中Pycharm 输出中文或打印中文乱码现象的解决办法
2017/06/16 Python
tornado 多进程模式解析
2018/01/15 Python
python验证码识别实例代码
2018/02/03 Python
pandas中去除指定字符的实例
2018/05/18 Python
Python 数据可视化pyecharts的使用详解
2019/06/26 Python
使用python将mysql数据库的数据转换为json数据的方法
2019/07/01 Python
使用jupyter notebook直接打开.md格式的文件
2020/04/10 Python
Python通过两个dataframe用for循环求笛卡尔积
2020/04/29 Python
Python性能分析工具py-spy原理用法解析
2020/07/27 Python
Python自动化测试中yaml文件读取操作
2020/08/20 Python
pycharm进入时每次都是insert模式的解决方式
2021/02/05 Python
DHC美国官网:日本通信销售第一的化妆品品牌
2017/11/12 全球购物
《找不到快乐的波斯猫》教学反思
2014/02/24 职场文书
农民工工资支付承诺函
2014/03/31 职场文书
春节联欢会策划方案
2014/05/16 职场文书
七夕相亲活动策划方案
2014/08/31 职场文书
2014矛盾纠纷排查调处工作总结
2014/12/09 职场文书
2015年见习期工作总结
2014/12/12 职场文书
幼儿园教师求职信
2015/03/20 职场文书
mysql优化之query_cache_limit参数说明
2021/07/01 MySQL
python数字转对应中文的方法总结
2021/08/02 Python