关于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 定界符 使用技巧
Jun 14 PHP
浅析php学习的路线图
Jul 10 PHP
解决phpcms更换javascript的幻灯片代码调用图片问题
Dec 26 PHP
smarty模板引擎使用内建函数foreach循环取出所有数组值的方法
Jan 22 PHP
ThinkPHP、ZF2、Yaf、Laravel框架路由大比拼
Mar 25 PHP
PHP 将数组打乱 shuffle函数的用法及简单实例
Jun 17 PHP
php根据用户名和手机号查询是否存在手机号码
Feb 16 PHP
PHP的PDO事务与自动提交
Jan 24 PHP
解决laravel5中auth用户登录其他页面获取不到登录信息的问题
Oct 08 PHP
在 Laravel 中动态隐藏 API 字段的方法
Oct 25 PHP
php面向对象基础详解【星际争霸游戏案例】
Jan 23 PHP
php+websocket 实现的聊天室功能详解
May 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 破解防盗链图片函数
2008/12/09 PHP
PHP 巧用数组降低程序的时间复杂度
2010/01/01 PHP
PHP5 字符串处理函数大全
2010/03/23 PHP
洪恩在线成语词典小偷程序php版
2012/04/20 PHP
php上传大文件设置方法
2016/04/14 PHP
PHP+ajax实现获取新闻数据简单示例
2018/05/08 PHP
Aster vs KG BO3 第二场2.19
2021/03/10 DOTA
JS的递增/递减运算符和带操作的赋值运算符的等价式
2007/12/08 Javascript
避免 showModalDialog 弹出新窗体的原因分析
2010/05/31 Javascript
基于jquery循环map功能的代码
2011/02/26 Javascript
js简单实现HTML标签Select联动带跳转
2013/10/23 Javascript
Jquery EasyUI中弹出确认对话框以及加载效果示例代码
2014/02/13 Javascript
jQuery简单实现title提示效果示例
2016/08/01 Javascript
JavaScript仿微信打飞机游戏
2020/07/05 Javascript
JavaScript模块详解
2017/12/18 Javascript
vue获取dom元素注意事项
2017/12/28 Javascript
elementUI select组件默认选中效果实现的方法
2019/03/25 Javascript
nodejs中request库使用HTTPS代理的方法
2019/04/30 NodeJs
微信小程序与公众号实现数据互通的方法
2019/07/25 Javascript
原生JavaScript实现留言板
2021/01/10 Javascript
Python函数嵌套实例
2014/09/23 Python
Python3 正在毁灭 Python的原因分析
2014/11/28 Python
Python中的hypot()方法使用简介
2015/05/18 Python
python文件特定行插入和替换实例详解
2017/07/12 Python
Python使用Selenium模块实现模拟浏览器抓取淘宝商品美食信息功能示例
2018/07/18 Python
python中cPickle类使用方法详解
2018/08/27 Python
windows下cx_Freeze生成Python可执行程序的详细步骤
2018/10/09 Python
基于TensorFlow中自定义梯度的2种方式
2020/02/04 Python
澳大利亚体育和露营装备在线/实体零售商:Find Sports
2020/06/03 全球购物
2014大学生批评与自我批评思想汇报
2014/09/21 职场文书
群众路线教育实践活动民主生活会个人检查对照思想汇报
2014/10/04 职场文书
2014年帮扶工作总结
2014/11/26 职场文书
师德先进个人材料
2014/12/20 职场文书
中标通知书范本
2015/04/17 职场文书
python实现高效的遗传算法
2021/04/07 Python
python实现图片批量压缩
2021/04/24 Python