关于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部分常见问题总结
Mar 27 PHP
php 生成饼图 三维饼图
Sep 28 PHP
JS与PHP向函数传递可变参数的区别实例代码
May 18 PHP
php 转换字符串编码 iconv与mb_convert_encoding的区别说明
Nov 10 PHP
PHP Parse Error: syntax error, unexpected $end 错误的解决办法
Jun 05 PHP
LotusPhp笔记之:基于ObjectUtil组件的使用分析
May 06 PHP
php实现文件编码批量转换
Mar 10 PHP
完美实现wordpress禁止文章修订和自动保存的方法
Nov 03 PHP
php去除头尾空格的2种方法
Mar 16 PHP
用PHP去掉文件头的Unicode签名(BOM)方法
Jun 22 PHP
PHP SFTP实现上传下载功能
Jul 26 PHP
PHP有序表查找之二分查找(折半查找)算法示例
Feb 09 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程序61条面向对象分析设计的经验小结
2008/11/12 PHP
php入门学习知识点三 PHP上传
2011/07/14 PHP
解析PHP函数array_flip()在重复数组元素删除中的作用
2013/06/27 PHP
Laravel模板引擎Blade中section的一些标签的区别介绍
2015/02/10 PHP
PHP5.3新特性小结
2016/02/14 PHP
php文件上传的两种实现方法
2016/04/04 PHP
php加密之discuz内容经典加密方式实例详解
2017/02/04 PHP
PHPMailer使用QQ邮箱实现邮件发送功能
2017/08/18 PHP
静态页面的值传递(三部曲)
2006/09/25 Javascript
jquery 图片轮换效果
2010/07/29 Javascript
jquery模拟SELECT下拉框取值效果
2013/10/23 Javascript
用JS实现3D球状标签云示例代码
2013/12/01 Javascript
使用javascript实现有效时间的控制,并显示将要过期的时间
2014/01/02 Javascript
判断日期是否能跨月查询的js代码
2014/07/25 Javascript
jQuery实现宽屏图片轮播实例教程
2015/11/24 Javascript
JavaScript使ifram跨域相互访问及与PHP通信的实例
2016/03/03 Javascript
jquery实现的table排序功能示例
2017/03/10 Javascript
在JS中如何把毫秒转换成规定的日期时间格式实例
2017/05/11 Javascript
JS中利用swiper实现3d翻转幻灯片实例代码
2017/08/25 Javascript
vue路由守卫+登录态管理实例分析
2019/05/21 Javascript
Python学习笔记之os模块使用总结
2014/11/03 Python
Python中转换角度为弧度的radians()方法
2015/05/18 Python
使用Python机器学习降低静态日志噪声
2018/09/29 Python
python实现的登录与提交表单数据功能示例
2019/09/25 Python
python同时遍历两个list用法说明
2020/05/02 Python
python将logging模块封装成单独模块并实现动态切换Level方式
2020/05/12 Python
英国异国风情旅游网站:Travel Talk Tours(团体旅游、探险旅游、帆船假期)
2018/07/26 全球购物
师范毕业生自荐信
2013/10/17 职场文书
大学生求职信例文
2014/06/29 职场文书
小学教师师德师风演讲稿
2014/08/22 职场文书
党的群众路线教育实践活动学习笔记范文
2014/11/06 职场文书
专家推荐信范文
2015/03/26 职场文书
解除处分决定书
2015/06/25 职场文书
公司团队口号霸气押韵
2015/12/24 职场文书
自考生自我评价
2019/06/21 职场文书
win10安装配置nginx的过程
2021/03/31 Servers