关于PHPDocument 代码注释规范的总结

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 <http://www.jb51.net>
* @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;
}
}
?>

(0)

相关推荐

  • PHP5中使用PDO连接数据库的方法

    1.PDO简介 PDO(PHP Data Object) 是PHP 5 中加入的东西,是PHP 5新加入的一个重大功能,因为在PHP 5以前的php4/php3都是一堆的数据库扩展来跟各个数据库的连接和处理,什么 php_mysql.dll.php_pgsql.dll.php_mssql.dll.php_sqlite.dll等等. PHP6中也将默认使用PDO的方式连接,mysql扩展将被作为辅助 2.PDO配置 PHP.ini中,去掉"extension=php_pdo.dll"前面

  • php实现基于PDO的预处理示例

    本文实例讲述了php实现基于PDO的预处理.分享给大家供大家参考,具体如下: $servername="localhost"; $username="root"; $password="admin"; //$dbname为我的test数据库 $dbname="test"; try{ $conn=new PDO("mysql:host=$servername;dbname=$dbname",$username

  • php使用pdo连接并查询sql数据库的方法

    本文实例讲述了php使用pdo连接并查询sql数据库的方法.分享给大家供大家参考. 具体实现代码如下: 复制代码 代码如下: $login = "root"; $passwd = "mysql"; try{   $db=new pdo('mysql:host=localhost;dbname=mysql',$login,$passwd);   foreach($db->query('select * from test') as $row){   print_

  • php PDO实现的事务回滚示例

    本文实例讲述了php PDO实现的事务回滚.分享给大家供大家参考,具体如下: $servername="localhost"; $username="root"; $password="admin"; $dbname="test"; try{ $conn=new PDO("mysql:host=$servername;dbname=$dbname",$username,$password); $conn-&

  • php中mysql连接方式PDO使用详解

    PDO常用方法: PDO::query()主要用于有记录结果返回的操作(PDOStatement),特别是select操作. PDO::exec()主要是针对没有结果集合返回的操作.如insert,update等操作.返回影响行数. PDO::lastInsertId()返回上次插入操作最后一条ID,但要注意:如果用insert into tb(col1,col2) values(v1,v2),(v11,v22)..的方式一次插入多条记录,lastinsertid()返回的只是第一条(v1,v2

  • php使用pdo连接报错Connection failed SQLSTATE的解决方法

    本文实例讲述了php pdo_mysql连接报错Connection failed: SQLSTATE[HY000] [2002] No such file or directory问题的解决方法.分享给大家供大家参考.具体方法如下: 错误描述: Connection failed: SQLSTATE[HY000] [2002] No such file or directory 环境概述: MacOS xampp 搭建的开发环境 apache mysql php xampp 已支持mysql

  • php pdo操作数据库示例

    POD扩展是在PHP5中加入,该扩展提供PHP内置类 PDO来对数据库进行访问,不同数据库使用相同的方法名,解决数据库连接不统一的问题. PDO的特点: 性能.PDO 从一开始就吸取了现有数据库扩展成功和失败的经验教训.因为 PDO 的代码是全新的,所以我们有机会重新开始设计性能,以利用 PHP 5 的最新特性. 能力.PDO 旨在将常见的数据库功能作为基础提供,同时提供对于 RDBMS 独特功能的方便访问. 简单.PDO 旨在使您能够轻松使用数据库.API 不会强行介入您的代码,同时会清楚地表

  • php中PDO方式实现数据库的增删改查

    需要开启php的pdo支持,php5.1以上版本支持 实现数据库连接单例化,有三要素 静态变量.静态实例化方法.私有构造函数 DPDO.php class DPDO{ private $DSN; private $DBUser; private $DBPwd; private $longLink; private $pdo; //私有构造函数 防止被直接实例化 private function __construct($dsn, $DBUser, $DBPwd, $longLink = fals

  • php基于PDO实现功能强大的MYSQL封装类实例

    本文实例讲述了php基于PDO实现功能强大的MYSQL封装类.分享给大家供大家参考,具体如下: class CPdo{ protected $_dsn = "mysql:host=localhost;dbname=test"; protected $_name = "root"; protected $_pass = ""; protected $_condition = array(); protected $pdo; protected $f

  • PHP PDO函数库(PDO Functions)第1/2页

    与ADODB和MDB2相比,PDO更高效.目前而言,实现"数据库抽象层"任重而道远,使用PDO这样的"数据库访问抽象层"是一个不错的选择. PDO->beginTransaction() - 标明回滚起始点 PDO->commit() - 标明回滚结束点,并执行SQL PDO->__construct() - 建立一个PDO链接数据库的实例 PDO->errorCode() - 获取错误码 PDO->errorInfo() - 获取错误

  • PHP实现PDO的mysql数据库操作类

    本文实例讲述了PHP实现PDO的mysql数据库操作类.分享给大家供大家参考.具体分析如下: dbconfig类负责配置数据库访问信息,包括:服务器地址.端口.数据库实例名.用户名.用户密码.字符集等. dbtemplate类集合了对数据库的访问操作,主要有以下几个操作: 1. queryrows:返回多行记录 2. queryrow:返回为单条记录 3. queryforint:查询单字段,返回整数 4. queryforfloat:查询单字段,返回浮点数(float) 5. queryfor

  • php_pdo 预处理语句详解

    这篇文章主要介绍的是关于php_pdo 预处理语句,下面话不多说,我们来看看详细的内容. 一.预处理语句可以带来两大好处: 1.查询仅需解析(或预处理)一次,但可以用相同或不同的参数执行多次.当查询准备好后,数据库将分析.编译和优化 执行该查询的计划.对于复杂的查询,此过程要花费较长的时间,如果需要以不同参数多次重复相同的查询,那么该过程将大 大降低应用程序的速度.通过使用预处理语句,可以避免重复分析/编译/优化周期.简言之,预处理语句占用更少的资源,因 而运行得更快. 2.提供给预处理语句的参

  • php使用PDO执行SQL语句的方法分析

    本文实例讲述了php使用PDO执行SQL语句的方法.分享给大家供大家参考,具体如下: exec()方法 exec()方法返回执行后受影响行数,语法如下: int PDO::exec(string statement) 参数statement是要执行的SQL语句.该方法返回执行查询时受影响的行数,通常情况下用于INSERT,DELETE和UPDATE语句中. 例如: $dbms='mysql';//数据库类型 $dbName='admin';//使用的数据库 $user='root';//数据库连

随机推荐