关于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+ajax做仿百度搜索下拉自动提示框(有实例)
Aug 21 PHP
php cc攻击代码与防范方法
Oct 18 PHP
配置php网页显示各种语法错误
Sep 23 PHP
CodeIgniter框架过滤HTML危险代码
Jun 12 PHP
ThinkPHP之foreach标签使用概述
Jun 30 PHP
thinkphp3.2.2实现生成多张缩略图的方法
Dec 19 PHP
PHP文件操作方法汇总
Jul 01 PHP
PHP判断字符串长度的两种方法很实用
Sep 22 PHP
在WordPress中实现发送http请求的相关函数解析
Dec 29 PHP
PHP实现动态执行代码的方法
Mar 25 PHP
浅谈PHP的$_SERVER[SERVER_NAME]
Feb 04 PHP
PHP判断密码强度的方法详解
May 26 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 正则表达式小结
2015/02/12 PHP
PHP生成图片验证码功能示例
2017/01/12 PHP
PHP中Cookie的使用详解(简单易懂)
2017/04/28 PHP
Yii实现微信公众号场景二维码的方法实例
2020/08/30 PHP
JavaScript 继承使用分析
2011/05/12 Javascript
开发 Internet Explorer 右键功能表(ContextMenu)
2013/07/03 Javascript
在JavaScript中访问字符串的子串
2015/07/07 Javascript
js重写方法的简单实现
2016/07/10 Javascript
vue实现ajax滚动下拉加载,同时具有loading效果(推荐)
2017/01/11 Javascript
使用bootstrap-paginator.js 分页来进行ajax 异步分页请求示例
2017/03/09 Javascript
VUE页面中加载外部HTML的示例代码
2017/09/20 Javascript
微信小程序实现MUI数字输入框效果
2018/01/31 Javascript
JavaScript格式化json和xml的方法示例
2019/01/22 Javascript
JS+canvas画布实现炫酷的旋转星空效果示例
2019/02/13 Javascript
Python循环语句之break与continue的用法
2015/10/14 Python
通过5个知识点轻松搞定Python的作用域
2016/09/09 Python
Python简单删除列表中相同元素的方法示例
2017/06/12 Python
Python实现对一个函数应用多个装饰器的方法示例
2018/02/09 Python
浅谈python的输入输出,注释,基本数据类型
2019/04/02 Python
Python 调用 Outlook 发送邮件过程解析
2019/08/08 Python
python实现智能语音天气预报
2019/12/02 Python
在Pycharm中安装Pandas库方法(简单易懂)
2021/02/20 Python
美国知名的摄影器材销售网站:Adorama
2017/02/01 全球购物
卡骆驰新加坡官网:Crocs新加坡
2018/06/12 全球购物
项目采购员岗位职责
2014/04/15 职场文书
一帮一活动总结
2014/05/08 职场文书
幼儿园优秀班主任事迹材料
2014/05/14 职场文书
泸县召开党的群众路线教育实践活动总结大会新闻稿
2014/10/21 职场文书
2014年家长学校工作总结
2014/11/20 职场文书
市级三好学生评语
2014/12/29 职场文书
2015年师德表现自我评价
2015/03/05 职场文书
起诉书格式范文
2015/05/20 职场文书
杨善洲电影观后感
2015/06/04 职场文书
讲座新闻稿
2015/07/18 职场文书
乡镇司法所2015年度工作总结
2015/10/14 职场文书
SpringDataJPA实体类关系映射配置方式
2021/12/06 Java/Android