phpDocumentor学习使用记录
phpDocumentor学习使用记录
一.phpDocumentor简介
PHPDocumentor是一个用PHP写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的API文档。老的版本是phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便。
phpDocumentor是一个非常强大的文档自动生成工具,利用它可以帮助我们编写规范的注释,生成易于理解,结构清晰的文档,对我们的代码升级,维护,移交等都有非常大的帮助。
二.那些元素可以生成文档
Function 函数
Constant 常量
Class 类
Interface 接口
Trait 特性
Class constant 类常量
Property 属性
Method 方法
File 文件
include/require声明 包含文件声明
Variable 变量
三.基本格式
1.Summary 总结
2.Description 详细描述
3.Tags and annotations 标签和注释
Example:
/**
* 函数add,实现两个数的加法
*
* 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
*
* @param int 加数
* @param int 被加数
* @return integer 返回值
*
*/
function Add($a, $b)
{
return $a+$b;
}
?>
用命令 phpdoc -d 项目绝对路径 -t 生成的文档存放的路径 生成文档
如下:
Add
integer Add( int $a, int $b)
[line 45]
函数add,实现两个数的加法
Constants 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
Parameters
・ int $a - 加数
・ int $b - 被加数
四.标签详细list
Tag | Element | Description |
api | Method | 用来声明一个结构元素是否可被用作第三方API |
author | Any | 创建者信息 |
category | File、class | 文件或者类所属的目录 |
copyright | Any | 版权信息 |
deprecated | Any | 此tag将在将来的版本中被弃用 |
example | Any | 这个tag指明示例代码的路径 |
filesource | File | 源文件输出 |
global | Variable | 全局变量 |
ignore | Any | 这个标签不会包括在文档中 |
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 | 指明当前元素的版本 |
五.类型
目前phpDocumentor中元素的各种标签需要和支持的各种类型。
1. 完整类名或者别名
使用它的完全限定类名(FQCN),这意味着类有一个前缀斜线,以表明它是类,如全名 \phpDocumentor\Descriptor\ClassDescriptor。
使用相对类名,例如 \Descriptor\ClassDescriptor。
用类的别名,例如 use phpDocumentorDescriptorParamDescriptor as Param
2. Php关键字
string
int or integer
float
bool or boolean
array
resource
null
callable
3. Phpdoc标准的关键字
mixed
void
object
false or true
self
static
$this
4. 联合类型
/** @return string|null */
六.运行phpDocumentor
Phpdoc
phpdoc run
phpdoc project:run
上面三个可以实现相同效果。
参数:
-d 项目源文件路径
-f 制定项目某一个文件
-t 生成文档的目录
phpdoc -d path/to/my/project -f path/to/an/additional/file -t path/to/my/output/folder
七.标签格式
1.@api
格式:@api
例如:
/**
*
* @api
*
*/
2. @author
格式:@author [name] [
例如:
/**
* @author My Name
* @author My Name <my.name@example.com>
*/
3. @category
格式:@category [description]
例如:
/**
* @category MyCategory
*/
4. @copyright
格式:@copyright [description]
例如:
/**
* @copyright 1997-2005 The PHP Group
*/
5. @deprecated
格式:@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.
*/
6. @example
格式:@example [location] [
例如:
/**
* @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.
*/
7. @filesource
格式:@filesource
例如:
/**
* @filesource
*/
8. @global
格式:@global [Type] [name] @global [Type] [description]
例如:
/**
* @global string $user
* @global string username
*/
9. @ignore
格式:@ignore [
例如:
/**
* @ignore
*/
10. @internal
格式:@internal [description]
例如:
/**
* @internal
*/
11. @license
格式:@license [
例如:
/**
* @license GPL
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*/
12.@link
格式:@link [URI] [
{@link [URI] [
例如:
/**
* @link http://example.com/my/bar Documentation 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.
*/
13. @method
格式:@method [return type] [name]([[type] [parameter]<, ...>]) [
例如:
/**
* @method string getString()
* @method void setInteger(integer $integer)
* @method setString(integer $integer)
*/
14. @package
格式:@package [level 1]\[level 2]\[etc.]
例如:
/**
* @package PSR\Documentation\API
*/
15. @param
格式:@param [Type] [name] [
例如:
/**
* @param mixed[] $items Array structure to count the elements of.
*/
16.@property
格式:@property [Type] [name] [
例如:
/**
* @property string $myProperty
*/
17. @property-read
格式:@property-read [Type] [name] [ 18. @property-write 格式:@property-write [Type] [name] [ 例如: 19.@return 格式:@return [Type] [ 例如: 20. @see 格式:@see [URI | FQSEN] [ 例如: 21. @since 格式:@since [version] [ 例如: 22. @source 格式:@source [ 例如: 23. @subpackage 格式:@subpackage [name] 例如: 24. @throws 格式:@throws [Type] [ 例如: 25. @todo 格式:@todo [description] 例如: 26. @uses 格式:@uses [FQSEN] [ 例如: 27. @var 格式:@var [“Type”] [$element_name] [ 例如: 28. @version 格式:@version [ 例如:
/**
* @property-read string $myProperty
*/
/**
* @property-write string $myProperty
*/
/**
* @return integer Indicates the number of items.
* @return string|null The label's text or null if none provided.
*/
/**
* @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.
*/
/**
* @since 1.0.2 Added the $b argument.
* @since 1.0.1 Added the $a argument.
* @since 1.0.0
*
*/
function dump($a, $b)
{
<...>
}
/**
* @source 2 1 Check that ensures lazy counting.
*/
/**
* @package PSR
* @subpackage Documentation\API
*/
/**
* @throws InvalidArgumentException if the provided argument is not
* of type 'array'.
*/
/**
* @todo add an array parameter to count
*/
/**
* @uses MyClass::$items to retrieve the count from.
*/
/** @var string|null Should contain a description
* @var string $name Should contain a description
* @var string $description Should contain a description
*/
/**
* @version 1.0.1
* @version GIT: $Id$ In development. Very unstable.
*/

热AI工具

Undresser.AI Undress
人工智能驱动的应用程序,用于创建逼真的裸体照片

AI Clothes Remover
用于从照片中去除衣服的在线人工智能工具。

Undress AI Tool
免费脱衣服图片

Clothoff.io
AI脱衣机

Video Face Swap
使用我们完全免费的人工智能换脸工具轻松在任何视频中换脸!

热门文章

热工具

记事本++7.3.1
好用且免费的代码编辑器

SublimeText3汉化版
中文版,非常好用

禅工作室 13.0.1
功能强大的PHP集成开发环境

Dreamweaver CS6
视觉化网页开发工具

SublimeText3 Mac版
神级代码编辑软件(SublimeText3)

会话劫持可以通过以下步骤实现:1.获取会话ID,2.使用会话ID,3.保持会话活跃。在PHP中防范会话劫持的方法包括:1.使用session_regenerate_id()函数重新生成会话ID,2.通过数据库存储会话数据,3.确保所有会话数据通过HTTPS传输。

JWT是一种基于JSON的开放标准,用于在各方之间安全地传输信息,主要用于身份验证和信息交换。1.JWT由Header、Payload和Signature三部分组成。2.JWT的工作原理包括生成JWT、验证JWT和解析Payload三个步骤。3.在PHP中使用JWT进行身份验证时,可以生成和验证JWT,并在高级用法中包含用户角色和权限信息。4.常见错误包括签名验证失败、令牌过期和Payload过大,调试技巧包括使用调试工具和日志记录。5.性能优化和最佳实践包括使用合适的签名算法、合理设置有效期、

在PHPStorm中如何进行CLI模式的调试?在使用PHPStorm进行开发时,有时我们需要在命令行界面(CLI)模式下调试PHP�...

SOLID原则在PHP开发中的应用包括:1.单一职责原则(SRP):每个类只负责一个功能。2.开闭原则(OCP):通过扩展而非修改实现变化。3.里氏替换原则(LSP):子类可替换基类而不影响程序正确性。4.接口隔离原则(ISP):使用细粒度接口避免依赖不使用的方法。5.依赖倒置原则(DIP):高低层次模块都依赖于抽象,通过依赖注入实现。

如何在系统重启后自动设置unixsocket的权限每次系统重启后,我们都需要执行以下命令来修改unixsocket的权限:sudo...

使用PHP的cURL库发送JSON数据在PHP开发中,经常需要与外部API进行交互,其中一种常见的方式是使用cURL库发送POST�...

静态绑定(static::)在PHP中实现晚期静态绑定(LSB),允许在静态上下文中引用调用类而非定义类。1)解析过程在运行时进行,2)在继承关系中向上查找调用类,3)可能带来性能开销。
