关于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 xml文件操作实现代码(二)
Mar 20 PHP
基于php设计模式中单例模式的应用分析
May 15 PHP
json的键名为数字时的调用方式(示例代码)
Nov 15 PHP
Smarty中调用FCKeditor的方法
Oct 27 PHP
thinkphp文件引用与分支结构用法实例
Nov 26 PHP
CI框架支持$_GET的两种实现方法
May 18 PHP
PHP文件上传操作实例详解
Sep 27 PHP
PHP使用微信开发模式实现搜索已发送图文及匹配关键字回复的方法
Sep 13 PHP
PHP实现的简单组词算法示例
Apr 10 PHP
PHP实现将多个文件压缩成zip格式并下载到本地的方法示例
May 23 PHP
解决Laravel5.2 Auth认证退出失效的问题
Oct 14 PHP
php获取是星期几的的一些常用姿势
Dec 15 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面向对象全攻略 (四)构造方法与析构方法
2009/09/30 PHP
《PHP编程最快明白》第六讲:Mysql数据库操作
2010/11/01 PHP
php格式化时间戳
2016/12/17 PHP
php实现文件预览功能
2017/05/23 PHP
对YUI扩展的Gird组件 Part-1
2007/03/10 Javascript
javascript之ESC(第二类混淆)
2007/05/06 Javascript
JS动画效果代码3
2008/04/03 Javascript
Jquery绑定事件(bind和live的区别介绍)
2013/08/23 Javascript
基于javascript、ajax、memcache和PHP实现的简易在线聊天室
2015/02/03 Javascript
JavaScript函数的一些注意要点小结及js匿名函数
2015/11/10 Javascript
jQuery mobile的header和footer在点击屏幕的时候消失的解决办法
2016/07/01 Javascript
实例解析angularjs的filter过滤器
2016/12/14 Javascript
JQuery ZTree使用方法详解
2017/01/07 Javascript
Angular4表单验证代码详解
2017/09/03 Javascript
浅谈vue引入css,less遇到的坑和解决方法
2018/01/20 Javascript
你可能不知道的CORS跨域资源共享
2019/03/13 Javascript
vue 地区选择器v-distpicker的常用功能
2019/07/23 Javascript
JS数组splice操作实例分析
2019/10/12 Javascript
在Vue项目中,防止页面被缩放和放大示例
2019/10/28 Javascript
不依任何赖第三方,单纯用vue实现Tree 树形控件的案例
2020/09/21 Javascript
python使用urllib模块和pyquery实现阿里巴巴排名查询
2014/01/16 Python
python3实现钉钉消息推送的方法示例
2019/03/14 Python
pyqt 多窗口之间的相互调用方法
2019/06/19 Python
python全栈要学什么 python全栈学习路线
2019/06/28 Python
Uber Eats台湾:寻找附近提供送餐服务的餐厅
2018/05/07 全球购物
String是最基本的数据类型吗?
2013/06/13 面试题
如何写你的创业计划书
2014/01/07 职场文书
吃空饷专项治理工作实施方案
2014/03/04 职场文书
大专生自我鉴定怎么写
2014/09/16 职场文书
2014年小学英语教师工作总
2014/12/03 职场文书
篮球赛闭幕式主持词
2015/07/03 职场文书
董事长新年致辞
2015/07/29 职场文书
golang DNS服务器的简单实现操作
2021/04/30 Golang
Pandas 稀疏数据结构的实现
2021/07/25 Python
vue @click.native 绑定原生点击事件
2022/04/22 Vue.js
Android开发实现极为简单的QQ登录页面
2022/04/24 Java/Android