溫馨提示×

您好，登錄后才能下訂單哦！

密碼登錄×
登錄注冊(cè)×
其他方式登錄
點(diǎn)擊 登錄注冊(cè) 即表示同意《億速云用戶服務(wù)條款》

phpDocumentor學(xué)習(xí)使用記錄

發(fā)布時(shí)間：2020-06-13 00:18:45 來源：網(wǎng)絡(luò) 閱讀：572 作者：wms3001 欄目：web開發(fā)

phpDocumentor學(xué)習(xí)使用記錄

一．phpDocumentor簡(jiǎn)介

PHPDocumentor是一個(gè)用PHP寫的工具，對(duì)于有規(guī)范注釋的php程序，它能夠快速生成具有相互參照，索引等功能的API文檔。老的版本是phpdoc，從1.3.0開始，更名為phpDocumentor，新的版本加上了對(duì)php5語(yǔ)法的支持，同時(shí)，可以通過在客戶端瀏覽器上操作生成文檔，文檔可以轉(zhuǎn)換為PDF,HTML,CHM幾種形式，非常的方便。

phpDocumentor是一個(gè)非常強(qiáng)大的文檔自動(dòng)生成工具，利用它可以幫助我們編寫規(guī)范的注釋，生成易于理解，結(jié)構(gòu)清晰的文檔，對(duì)我們的代碼升級(jí)，維護(hù),移交等都有非常大的幫助。

二．那些元素可以生成文檔

Function 函數(shù)

Constant 常量

Class 類

Interface 接口

Trait 特性

Class constant 類常量

Property 屬性

Method 方法

File 文件

include/require聲明 包含文件聲明

Variable 變量

三．基本格式

1.Summary 總結(jié)

2.Description 詳細(xì)描述

3.Tags and annotations 標(biāo)簽和注釋

Example:

<?php

/**

* 函數(shù)add,實(shí)現(xiàn)兩個(gè)數(shù)的加法

*

* 一個(gè)簡(jiǎn)單的加法計(jì)算，函數(shù)接受兩個(gè)數(shù)a、b，返回他們的和c

*

* @param int 加數(shù)

* @param int 被加數(shù)

* @return integer 返回值

*

*/

function Add($a, $b)

{

return $a+$b;

}

?>

用命令 phpdoc -d 項(xiàng)目絕對(duì)路徑 -t 生成的文檔存放的路徑 生成文檔

如下：

Add

integer Add( int $a, int $b)

[line 45]

函數(shù)add,實(shí)現(xiàn)兩個(gè)數(shù)的加法

Constants 一個(gè)簡(jiǎn)單的加法計(jì)算，函數(shù)接受兩個(gè)數(shù)a、b，返回他們的和c

Parameters

· int $a - 加數(shù)

· int $b - 被加數(shù)

四．標(biāo)簽詳細(xì)list

Tag

Element

Description

api

Method

用來聲明一個(gè)結(jié)構(gòu)元素是否可被用作第三方API

author

Any

創(chuàng)建者信息

category

File、class

文件或者類所屬的目錄

copyright

Any

版權(quán)信息

deprecated

Any

此tag將在將來的版本中被棄用

example

Any

這個(gè)tag指明示例代碼的路徑

filesource

File

源文件輸出

global

Variable

全局變量

ignore

Any

這個(gè)標(biāo)簽不會(huì)包括在文檔中

internal

Any

這個(gè)標(biāo)簽僅在應(yīng)用程序和內(nèi)部庫(kù)使用

license

File, Class

文件和類的許可證信息

link

Any

指明元素和網(wǎng)站的鏈接關(guān)系

method

Class

指明類可用的魔術(shù)方法

package

File, Class

文件和類所屬的包信息

param

Method,Function

方法和函數(shù)的參數(shù)信息

property

Class

類的屬性信息

property-read

Class

類的只讀屬性信息

property-write

Class

類的只寫屬性信息

return

Method,Function

方法和函數(shù)的返回值

see

Any

指明參考引用出處

since

Any

元素從那個(gè)版本起用

source

Any, except File

顯示元素的源代碼

subpackage

File, Class

指明類和文件的子包

throws

Method,Function

指明元素可能拋出的異常

todo

Any

指明這個(gè)元素正在開發(fā)中

uses

Any

指明元素引用的其他元素

var

Properties

指明類的屬性

version

Any

指明當(dāng)前元素的版本

五．類型

目前phpDocumentor中元素的各種標(biāo)簽需要和支持的各種類型。

1. 完整類名或者別名

使用它的完全限定類名（FQCN），這意味著類有一個(gè)前綴斜線，以表明它是類，如全名 \phpDocumentor\Descriptor\ClassDescriptor。

使用相對(duì)類名，例如 \Descriptor\ClassDescriptor。

用類的別名，例如 use phpDocumentorDescriptorParamDescriptor as Param

2. Php關(guān)鍵字

string

int or integer

float

bool or boolean

array

resource

null

callable

3. Phpdoc標(biāo)準(zhǔn)的關(guān)鍵字

mixed

void

object

false or true

self

static

$this

4. 聯(lián)合類型

/** @return string|null */

六．運(yùn)行phpDocumentor

Phpdoc

phpdoc run

phpdoc project:run

上面三個(gè)可以實(shí)現(xiàn)相同效果。

參數(shù)：

-d 項(xiàng)目源文件路徑

-f 制定項(xiàng)目某一個(gè)文件

-t 生成文檔的目錄

phpdoc -d path/to/my/project -f path/to/an/additional/file -t path/to/my/output/folder

七．標(biāo)簽格式

1.@api

格式：@api

例如：

/**

*

* @api

*

*/

2. @author

格式：@author [name] [<email address>]

例如：

/**
     * @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 [<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.
      */
 
向AI問一下細(xì)節(jié)

免責(zé)聲明：本站發(fā)布的內(nèi)容（圖片、視頻和文字）以原創(chuàng)、轉(zhuǎn)載和分享為主，文章觀點(diǎn)不代表本網(wǎng)站立場(chǎng)，如果涉及侵權(quán)請(qǐng)聯(lián)系站長(zhǎng)郵箱：is@yisu.com進(jìn)行舉報(bào)，并提供相關(guān)證據(jù)，一經(jīng)查實(shí)，將立刻刪除涉嫌侵權(quán)內(nèi)容。

AI
助
手