关于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 远程关机操作的代码
Dec 05 PHP
setcookie中Cannot modify header information-headers already sent by错误的解决方法详解
May 08 PHP
PHP统计二维数组元素个数的方法
Nov 12 PHP
php数组排序usort、uksort与sort函数用法
Nov 17 PHP
php数组查找函数总结
Nov 18 PHP
ThinkPHP框架设计及扩展详解
Nov 25 PHP
PHP中SimpleXML函数用法分析
Nov 26 PHP
WebQQ最新登陆协议的用法
Dec 22 PHP
浅谈php命令行用法
Feb 04 PHP
win平台安装配置Nginx+php+mysql 环境
Jan 12 PHP
PHP微信公众号自动发送红包API
Jun 01 PHP
PHP从尾到头打印链表实例讲解
Sep 27 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加密扩展库Mcrypt安装和实例
2013/11/10 PHP
php通过数组实现多条件查询实现方法(字符串分割)
2014/05/06 PHP
php获取、检查类名、函数名、方法名的函数方法
2015/06/25 PHP
PHP+Jquery与ajax相结合实现下拉淡出瀑布流效果【无需插件】
2016/05/06 PHP
javascript基础的动画教程,直观易懂
2007/01/10 Javascript
Javascript Math ceil()、floor()、round()三个函数的区别
2010/03/09 Javascript
js中获取事件对象的方法小结
2011/03/13 Javascript
jquery插件star-rating.js实现星级评分特效
2015/04/15 Javascript
js实现input框文字动态变换显示效果
2015/08/19 Javascript
js钢琴按钮波浪式图片排列效果代码分享
2015/08/26 Javascript
JQuery.validate在ie8下不支持的快速解决方法
2016/05/18 Javascript
简单模拟node.js中require的加载机制
2016/10/27 Javascript
JavaScript实现的select点菜功能示例
2017/01/16 Javascript
js实现下拉框效果(select)
2017/03/28 Javascript
解决Vue2.0自带浏览器里无法打开的原因(兼容处理)
2017/07/28 Javascript
Vue v2.5 调整和更新不完全问题
2017/10/24 Javascript
JS实现非首屏图片延迟加载的示例
2018/01/06 Javascript
JS随机数产生代码分享
2018/02/24 Javascript
微信小程序搭建(mpvue+mpvue-weui+fly.js)的详细步骤
2018/09/18 Javascript
微信小程序绑定手机号获取验证码功能
2019/10/22 Javascript
Vuex实现数据共享的方法
2019/12/20 Javascript
通过angular CDK实现页面元素拖放的步骤详解
2020/07/01 Javascript
Python实现的科学计算器功能示例
2017/08/04 Python
python实现字符串加密成纯数字
2019/03/19 Python
Django中自定义查询对象的具体使用
2019/10/13 Python
python+tifffile之tiff文件读写方式
2020/01/13 Python
解决python运行效率不高的问题
2020/07/20 Python
jupyter使用自动补全和切换默认浏览器的方法
2020/11/18 Python
详解如何修改jupyter notebook的默认目录和默认浏览器
2021/01/24 Python
生物技术毕业生自荐信
2013/10/23 职场文书
社区国庆节活动方案
2014/02/05 职场文书
2014年安置帮教工作总结
2014/12/11 职场文书
离婚案件原告代理词
2015/05/23 职场文书
2015年国庆节广播稿
2015/08/19 职场文书
Python利器openpyxl之操作excel表格
2021/04/17 Python
centos8安装MongoDB的详细过程
2021/10/24 MongoDB