phpDocumentor学习使用记录-php教程-PHP中文網

首頁

後端開發

php教程

phpDocumentor学习使用记录

WBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWBOYWB

Jun 23, 2016 pm 01:28 PM

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 [] [name]

例如：

/**

       * @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] [

       例如：

/**

         * @property-read string $myProperty

*/

18. @property-write

格式：@property-write [Type] [name] []

例如：

/**

        * @property-write string $myProperty

*/

19．@return

格式：@return [Type] []

例如：

/**

         * @return integer Indicates the number of items.

         * @return string|null The label's text or null if none provided.

*/

20. @see

格式：@see [URI | FQSEN] []

例如：

/**

        * @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] []

例如：

/**

      * @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 [ [] ] []

例如：

/**

      * @source 2 1 Check that ensures lazy counting.

*/

23. @subpackage

格式：@subpackage [name]

例如：

/**

      * @package PSR

      * @subpackage Documentation\API

*/

24. @throws

格式：@throws [Type] []

例如：

/**

      * @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] []

例如：

/**

      * @uses MyClass::$items to retrieve the count from.

*/

27. @var

格式：@var [“Type”] [$element_name] []

例如：

    /** @var string|null Should contain a description

      * @var string $name        Should contain a description

      * @var string $description Should contain a description

*/

28. @version

格式：@version [] []

/**

      * @version 1.0.1

      * @version GIT: $Id$ In development. Very unstable.

*/

陳述

本文內容由網友自願投稿，版權歸原作者所有。本站不承擔相應的法律責任。如發現涉嫌抄襲或侵權的內容，請聯絡admin@php.cn

您如何防止與會議有關的跨站點腳本（XSS）攻擊？Apr 23, 2025 am 12:16 AM

要保護應用免受與會話相關的XSS攻擊，需採取以下措施：1.設置HttpOnly和Secure標誌保護會話cookie。 2.對所有用戶輸入進行輸出編碼。 3.實施內容安全策略(CSP)限制腳本來源。通過這些策略，可以有效防護會話相關的XSS攻擊，確保用戶數據安全。

您如何優化PHP會話性能？Apr 23, 2025 am 12:13 AM

优化PHP会话性能的方法包括：1.延迟会话启动，2.使用数据库存储会话，3.压缩会话数据，4.管理会话生命周期，5.实现会话共享。这些策略能显著提升应用在高并发环境下的效率。

什麼是session.gc_maxlifetime配置設置？Apr 23, 2025 am 12:10 AM

theSession.gc_maxlifetimesettinginphpdeterminesthelifespanofsessiondata，setInSeconds.1）它'sconfiguredinphp.iniorviaini_set（）.2）abalanceisesneededeededeedeedeededto toavoidperformance andunununununexpectedLogOgouts.3）

您如何在PHP中配置會話名？Apr 23, 2025 am 12:08 AM

在PHP中，可以使用session_name()函數配置會話名稱。具體步驟如下：1.使用session_name()函數設置會話名稱，例如session_name("my_session")。 2.在設置會話名稱後，調用session_start()啟動會話。配置會話名稱可以避免多應用間的會話數據衝突，並增強安全性，但需注意會話名稱的唯一性、安全性、長度和設置時機。

您應該多久再生一次會話ID？Apr 23, 2025 am 12:03 AM

會話ID應在登錄時、敏感操作前和每30分鐘定期重新生成。 1.登錄時重新生成會話ID可防會話固定攻擊。 2.敏感操作前重新生成提高安全性。 3.定期重新生成降低長期利用風險，但需權衡用戶體驗。

如何在PHP中設置會話cookie參數？Apr 22, 2025 pm 05:33 PM

在PHP中設置會話cookie參數可以通過session_set_cookie_params()函數實現。 1)使用該函數設置參數，如過期時間、路徑、域名、安全標誌等；2)調用session_start()使參數生效；3)根據需求動態調整參數，如用戶登錄狀態；4)注意設置secure和httponly標誌以提升安全性。