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:
<?php
/**
* 函數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
七．標籤格式
格式：@api
例如：
/**
*
* @api
*
*/
2. @author
格式：@author [name] [<email address>]
例如：
/**
* @author My Name
* @author My Name <[email protected]>
*/
3. @category
格式：@category [description]
例如：
/**
* @category MyCategory
*/
4. @copyright
格式：@copyright [description]
例如：
/**
* @copyright 1997-2005 The PHP Group
*/
5. @deprecated
格式：@deprecated [<version>] [<description>]
例如：
/**
* @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] [<start-line> [<number-of-lines>] ] [<description>]
例如：
/**
* @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 [<description>]
例如：
/**
* @ignore
*/
10. @internal
格式：@internal [description]
例如：
/**
* @internal
*/
11. @license
格式：@license [<url>] [name]
例如：
/**
* @license GPL
* @license http://opensource.org/licenses/gpl-license.php GNU Public License
*/
12.@link
格式：@link [URI] [<description>]
{@link [URI] [<description>]}
例如：
/**
* @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]<, ...>]) [<description>]
例如：
/**
* @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] [<description>]
例如：
/**
* @param mixed[] $items Array structure to count the elements of.
*/
16．@property
格式：@property [Type] [name] [<description>]
例如：
/**
* @property string $myProperty
*/
17. @property-read
格式：@property-read [Type] [name] [<description]
例如：
/**
* @property-read string $myProperty
*/
18. @property-write
格式：@property-write [Type] [name] [<description>]
例如：
/**
* @property-write string $myProperty
*/
19．@return
格式：@return [Type] [<description>]
例如：
/**
* @return integer Indicates the number of items.
* @return string|null The label's text or null if none provided.
*/
20. @see
格式：@see [URI | FQSEN] [<description>]
例如：
/**
* @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.
*/
21. @since
格式：@since [version] [<description>]
例如：
/**
* @since 1.0.2 Added the $b argument.
* @since 1.0.1 Added the $a argument.
* @since 1.0.0
*
*/
function dump($a, $b)
{
<...>
}
22. @source
格式：@source [<start-line> [<number-of-lines>] ] [<description>]
例如：
/**
* @source 2 1 Check that ensures lazy counting.
*/
23. @subpackage
格式：@subpackage [name]
例如：
/**
* @package PSR
* @subpackage Documentation\API
*/
24. @throws
格式：@throws [Type] [<description>]
例如：
/**
* @throws InvalidArgumentException if the provided argument is not
* of type 'array'.
*/
25. @todo
格式：@todo [description]
例如：
/**
* @todo add an array parameter to count
*/
26. @uses
格式：@uses [FQSEN] [<description>]
例如：
/**
* @uses MyClass::$items to retrieve the count from.
*/
27. @var
格式：@var [“Type”] [$element_name] [<description>]
例如：
/** @var string|null Should contain a description
* @var string $name Should contain a description
* @var string $description Should contain a description
*/
28. @version
格式：@version [<vector>] [<description>]
/**
* @version 1.0.1
* @version GIT: $Id$ In development. Very unstable.
*/