PHPDocumentor 整理目光规范
2015-12-10 19:18
721 查看
你会写凝视么?从我写代码開始。这个问题就一直困扰着我。相信也相同困扰着其它同学。曾经的写凝视总是没有一套行之有效的标准,给维护和协同开发带了很多麻烦,直到近期读到了phpdocumentor的凝视标准。
以下对phpdocumentor的凝视标准进行总结:
Type(数据类型):string
字符串类型
integer or
int
整型
boolean or
bool
布尔类型 true or false
float or
double
浮点类型
object
对象
mixed
混合类型
没有指定类型或不确定类型时使用
array
数组
resource
资源类型
(如数据库查询返回)
void
空值(控制器返回值常常使用)
null null类型
callable
回调函数
false or
true
仅仅返回true or fasle
时使用
self
自身
Tags(标签):
Tag | Element | Description |
api | Methods | 声明接口 |
author | Any | 作者信息 |
category | File, Class | 将一系列的元素分类在一起 |
copyright | Any | 版权信息 |
deprecated | Any | 声明元素已被弃用,能够在将来的版本号中删除 |
example | Any | 演示样例 |
filesource | File | 文件资源 |
global | Variable | 声明一个全集变量 |
ignore | Any | 忽略当前元素 (phpdocumentor 生成文档时) |
internal | Any | 声明一个值为整形,或者设置一个应用的默认值为整型 |
license | File, Class | 声明许可类型 |
link | Any | 声明一个和当前元素有关的链接 |
method | Class | 声明当前类那些魔术方法能够被调用 |
package | File, Class | 声明当前元素所属的包 |
param | Method, Function | 声明当前元素的一个參数 |
property | Class | 声明当前类有那些魔术方法能够被调用属性 |
property-read | Class | 声明当前类有那些魔术方法能够读取属性 |
property-write | Class | 声明当前类有那些魔术方法能够设置属性 |
return | Method, Function | 返回值 |
see | Any | 说明当前元素參数引用于其它网站或元素 |
since | Any | 声明当前元素始于于哪个版本号 |
source | Any, except File | 展示当前元素的源代码 |
subpackage | File, Class | 将当期元素分类 |
throws | Method, Function | 说明当前元素抛出的异常 |
todo | Any | 说明当前元素的开发活动 |
uses | Any | 引用一个关联元素 |
var | Properties | 声明属性 |
version | Any | 版本号 |
// =============================
@api
/** * This method will not change until a major release. * * @api * * @return void */ function showVersion() { <...> }
// =============================
@author
/** * @author My Name * @author My Name <my.name@example.com> */
// =============================
@category
/** * Page-Level DocBlock * * @category MyCategory * @package MyPackage */
// =============================
@copyright
/** * @copyright 1997-2005 The PHP Group */
// =============================
@deprecated
/** * @deprecated * @deprecated 1.0.0 * @deprecated No longer used by internal code and not recommended. * @deprecated 1.0.0 No longer used by internal code and not recommended. */ function count() { <...> }
// =============================
@example
/** * @example example1.php Counting in action. * @example http://example.com/example2.phps Counting in action by a 3rd party. * @example "My Own Example.php" My counting. */ function count() { <...> }
// =============================
@filesource
/** * @filesource */
// =============================
@global
phpdocumentor2.0不支持
// =============================
@ignore
if ($ostest) { /** * This define will either be 'Unix' or 'Windows' */ define("OS","Unix"); } else { /** * @ignore */ define("OS","Windows"); }
// =============================
@internal
/** * @internal * * @return integer Indicates the number of items. */ function count() { <...> }
/** * Counts the number of Foo. * * {@internal Silently adds one extra Foo to compensate for lack of Foo }} * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@license
/** * @license GPL * @license http://opensource.org/licenses/gpl-license.php GNU Public License */
// =============================
@link
/** * @link http://example.com/my/bar Documentation of Foo. * * @return integer Indicates the number of items. */ function count() { <...> }
/** * This method counts the occurrences of Foo. * * When no more Foo ({@link http://example.com/my/bar}) are given this * function will add one as there must always be one Foo. * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@method
class Parent { public function __call() { <...> } } /** * @method string getString() * @method void setInteger(integer $integer) * @method setString(integer $integer) */ class Child extends Parent { <...> }
// =============================
@package
/** * @package PSR\Documentation\API */
// =============================
@param
/** * Counts the number of items in the provided array. * * @param mixed[] $items Array structure to count the elements of. * * @return int Returns the number of elements. */ function count(array $items) { <...> }
// =============================
@property
class Parent { public function __get() { <...> } } /** * @property string $myProperty */ class Child extends Parent { <...> }
// =============================
@property-read
class Parent { public function __get() { <...> } } /** * @property-read string $myProperty */ class Child extends Parent { <...> }
// =============================
@property-write
class Parent { public function __set() { <...> } } /** * @property-write string $myProperty */ class Child extends Parent { <...> }
// =============================
@return
/** * @return integer Indicates the number of items. */ function count() { <...> }
/** * @return string|null The label's text or null if none provided. */ function getLabel() { <...> }
// =============================
@see
/** * @see http://example.com/my/bar Documentation of Foo. * @see MyClass::$items for the property whose items are counted * @see MyClass::setItems() to set the items for this collection. * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@since
/** * @since 1.0.1 First time this was introduced. * * @return integer Indicates the number of items. */ function count() { <...> }
/** * @since 1.0.2 Added the $b argument. * @since 1.0.1 Added the $a argument. * @since 1.0.0 * * @return void */ function dump($a, $b) { <...> }
// =============================
@source
/** * @source 2 1 Check that ensures lazy counting. */ function count() { if (null === $this->count) { <...> } }
// =============================
@subpackage
/** * @package PSR * @subpackage Documentation\API */
// =============================
@throws
/** * Counts the number of items in the provided array. * * @param mixed[] $array Array structure to count the elements of. * * @throws InvalidArgumentException if the provided argument is not of type * 'array'. * * @return int Returns the number of elements. */ function count($items) { <...> }
// =============================
@todo
/** * Counts the number of items in the provided array. * * @todo add an array parameter to count * * @return int Returns the number of elements. */ function count() { <...> }
// =============================
@uses
/** * @uses MyClass::$items to retrieve the count from. * * @return integer Indicates the number of items. */ function count() { <...> }
// =============================
@var
class Counter { /** * @var */ public $var; }
// =============================
@version
/** * @version 1.0.1 */ class Counter { <...> }
/** * @version GIT: $Id$ In development. Very unstable. */ class NeoCounter { <...> }
// =============================
phpdocumentor手冊:http://www.phpdoc.org/docs/latest/index.html
(我有限的英语水平,假设不当翻译,请建议,当然,及时修正)
相关文章推荐
- php通过odbc连接sqlserver
- 使用RPM实现LAMP的配置(Wordpress、phpmyadmin)
- php递归循环地区
- php中ssl开发的若干问题
- Yii2.0 数据库操作
- php源码分析之PHPAPI宏的作用
- mac下搭建php环境
- php 5.4 安装 pthreads
- php中设置错误报告级别error_reporting()
- webstorm11.0.1 phpstorm10.0.1 汉化版 破解版 免费版
- vsftpd使用总结
- thinkphp 下url模式为伪静态的情况下翻页出现问题的解决方式。
- 【php】获取路径(目录)
- Ubuntu下安装PHP
- thinkphp 邮件发送
- 利用cookie来写计时器和历史记录(简略)
- yum php56
- php webp转jpg
- 老李分享知识:性能测试之TPS和吞吐率
- java 时间戳和PHP时间戳 的转换[10位和13位]