- 浏览: 16037 次
- 性别:
- 来自: 河南
最新评论
良好的文档注释不但能使代码易于维护,而且可以通过phpDocumentor等文档生成工具生成项目手册,以便于查阅。此外PHP的弱类型特征更应该引起我们对文档注释的重视!
本文简单的介绍下PHPDoc文档注释,以及常用的一些标签。
1. 文档注释并不只是用来注释整个文件的,在元素前面声明之后,它可以和该特定的程序元素相关联,例如类、函数、常量、变量、方法等等,以/**开头、*/结束,注意注释与相关联的程序元素间不能有空行;
2. 常用的标签
@author Author Name [<author@email.com>] 代码编写人(负责人)
@version xx.xx 当前版本号
@param datatype $v_name[,...] description 函数相关联的参数,含有,...表示可传入不定数量的其他参数
@return datatype description 函数或方法的返回值类型
@global datatype description 全局变量的说明(仅对phpDocumentor解析器起作用)
@var datatype 在类中说明类变量(属性)的类型
@example [path|url] description 举一个例子,以阐释使用方法
@todo description 待完成的工作信息或待解决的问题信息
更多的标签请参考 http://en.wikipedia.org/wiki/Phpdoc
这里举一个Zend Framework里的一段代码为例:
本文简单的介绍下PHPDoc文档注释,以及常用的一些标签。
1. 文档注释并不只是用来注释整个文件的,在元素前面声明之后,它可以和该特定的程序元素相关联,例如类、函数、常量、变量、方法等等,以/**开头、*/结束,注意注释与相关联的程序元素间不能有空行;
2. 常用的标签
@author Author Name [<author@email.com>] 代码编写人(负责人)
@version xx.xx 当前版本号
@param datatype $v_name[,...] description 函数相关联的参数,含有,...表示可传入不定数量的其他参数
@return datatype description 函数或方法的返回值类型
@global datatype description 全局变量的说明(仅对phpDocumentor解析器起作用)
@var datatype 在类中说明类变量(属性)的类型
@example [path|url] description 举一个例子,以阐释使用方法
@todo description 待完成的工作信息或待解决的问题信息
更多的标签请参考 http://en.wikipedia.org/wiki/Phpdoc
这里举一个Zend Framework里的一段代码为例:
<?php /** * Zend Framework * * LICENSE * * This source file is ... * * @category Zend * @package Zend_Db * @subpackage Adapter * @copyright Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com) * @license http://framework.zend.com/license/new-bsd New BSD License * @version $Id: Abstract.php 19115 2009-11-20 17:41:25Z matthew $ */ /** * @see Zend_Db */ require_once 'Zend/Db.php'; /** * Class for connecting to SQL databases and performing common operations. * * @category Zend * @package Zend_Db * @subpackage Adapter * @copyright Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com) * @license http://framework.zend.com/license/new-bsd New BSD License */ abstract class Zend_Db_Adapter_Abstract { /** * User-provided configuration * * @var array */ protected $_config = array(); /** * Constructor. * * $config is an array of key/value pairs or an instance of Zend_Config * containing configuration options. These options are common to most adapters: * * dbname => (string) The name of the database to user * username => (string) Connect to the database as this username. * password => (string) Password associated with the username. * host => (string) What host to connect to, defaults to localhost * * Some options are used on a case-by-case basis by adapters: * * port => (string) The port of the database * persistent => (boolean) Whether to use a persistent connection or not, defaults to false * protocol => (string) The network protocol, defaults to TCPIP * caseFolding => (int) style of case-alteration used for identifiers * * @param array|Zend_Config $config An array or instance of Zend_Config having configuration data * @throws Zend_Db_Adapter_Exception */ public function __construct($config) { /* * Verify that adapter parameters are in an array. */ if (!is_array($config)) { /* * Convert Zend_Config argument to a plain array. */ if ($config instanceof Zend_Config) { $config = $config->toArray(); } else { /** * @see Zend_Db_Adapter_Exception */ require_once 'Zend/Db/Adapter/Exception.php'; throw new Zend_Db_Adapter_Exception('Adapter parameters must be in an array or a Zend_Config object'); } } //后面略...
发表评论
-
php 将数组写入文本或数据库
2012-02-24 11:51 0//将一个测试的数组写 ... -
五种常见的 PHP 设计模式
2012-02-23 14:52 0http://www.ibm.com/developerwor ... -
get_object_vars
2012-02-23 13:26 0array_map get_object_vars __LI ... -
php简单对象与数组的转换函数代码(php多层数组和对象的转换)
2012-02-23 13:23 903function arrayToObject($e){ ... -
PHP编码规范2
2011-11-03 10:53 10121 介绍 为了更好的提高开发的工作效率,保证开 ... -
PHP编码规范
2011-11-03 10:52 6641. 介绍 1.1. 标准化的重 ... -
PHP反射API
2011-09-20 11:12 875反射是什么? 它是指在PHP运行状态中,扩展分析PHP程序,导 ... -
PHP number_format() 函数
2011-09-13 23:44 1430格式化数字 函数number_format 和 round ... -
PHP socket 网络编程实例
2011-09-08 01:22 894SERVER端 <?php ... -
php 分隔字符串为数组
2011-08-28 01:38 1198explode explode — 使用一个字符串分割另一个 ... -
phpDocumentor
2011-08-27 03:51 8181. 什么是phpDocumentor ? PHP ... -
php DOC类型注释的用法
2011-08-27 03:26 913/** * @name 名字 * @abstract ... -
php 保存远程图片到本地
2011-08-27 02:10 1056<?php header('C ...
相关推荐
《PHP文档规范及phpDoc指南-共享版》主要内容是介绍如何写PHP文档和注释,还有phpdoc的使用指南。 适用人群:PHP程序员、工程师、技术经理、架构师和技术总监
HPDocumentor是一个用PHP写的工具,对于有规范注释的php程序,它...老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可...
用过IDE或看过其他源码...PHPDoc 是一个 PHP 版的 Javadoc。它是一种注释 PHP 代码的正式标准。它支持通过类似 phpDocumentor 这样的外部文档生成器生成 API 文档,也可以帮助一些例如 Zend Studio, NetBeans, ActiveSt
swagger-php, php swagger注释和解析库 swagger-php为你的RESTful API生成交互式的文档,使用 Doctrine 注释。特性Swagger 2.0规范兼容。异常错误报告( 带有提示,上下文)从代码&中提取现有的phpdoc注
老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便。 PHPDocumentor工作时,...
简介:这是一个用PHP写的工具,对于有规范注释的php程序,它...老的版本是 phpdoc,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便。
从代码和现有的phpdoc注释中提取信息。 命令行界面可用。 文档站点,以及入门指南。 出色的错误报告(带有提示,上下文)(使用Composer安装),composer需要zircote / swagger-php,以便从任何地方使用cli全局安装...
从代码和现有的phpdoc注释中提取信息。 命令行界面可用。 ,以及入门指南。 异常错误报告(带有提示,上下文)安装(使用 ) composer require zircote/swagger-php 为了从任何地方使用cli,请在全局安装swagger-...
老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便。 PHPDocumentor工作时,...