php documentor

2011 Aircamel Copyright 1

PHPDOCUMENTOR

使用及方法簡要Cloud


文件的重要 “Writing good documentation is essential

to the success of any software project.”http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.pkg.html

特別是 OOS 項目

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.pkg.html




文件的類型 Client User

教學或使用文件

開發人員案例： API 文檔


What’s phpDocumentor

HPDocumentor 是一個用 PHP 寫的工具，對於有規範註釋的 php 程式。

它能夠快速生成具有相互參照 , 索引等功能的 API 文檔。

可以通過在客戶端瀏覽器上操作生成文檔，文檔可以轉換為 PDF,HTML,CHM 幾種形式，非常的方便。


How’s Work

掃描指定目錄下面的 php 原始碼，掃描其中的關鍵字，截取須要分析的註釋，然後分析註釋中的專用的 tag ，生成 xml文件

接着根據已經分析完的類別和區塊的訊息，建立相應的索引，生成 xml 文件

對於生成的 xml 文件，運用定制的模板輸出為指定格式的文件

6

Example

PEAR API Documentation http://

pear.php.net/package/Auth/docs/latest/

Zend Framework http://framework.zend.com/apidoc/core

symfony http://www.symfony-project.org/api/1_2

2011 Aircamel Copyright

http://pear.php.net/package/Auth/docs/latest/



http://framework.zend.com/apidoc/core



http://www.symfony-project.org/api/1_2




How to Install

phpDocumentor 的安裝分為自動安裝和手動安裝兩種方式

通過 pear 自動安裝pear install PhpDocumentor

手動安裝在 http://manual.phpdoc.org/下載最新版本的PhpDocumentor 把內容解壓即可。

http://manual.phpdoc.org/


如何使用所有的註釋都是由 /** 開始的一個多行註釋，

在 phpDocumentor 裡稱為 DocBlock, DocBlock 是指軟體開發人員編寫的關於某個關鍵字的幫助訊息，使得其他人能夠通過它知道這個關鍵字的具體用途，如何運用。

PhpDocumentor 規定一個 DocBlock 包含如下訊息：功能簡述區 (Short Description)詳細說明區 (Long Description)標記 tag


DocBlock /**

* Short description * * Long description. This is an sample function * to show the DocBlock format. * * 2nd paragraph of long description. * * * @tag1 * @tag2 */


Short Description

正文一般是簡明扼要地說明這個類別，方法或者函數的功能。

功能簡述的正文在生成的文檔中將顯示在索引區。

功能描述區的內容可以通過一個空行或者 */ 來結束。


Long Description

在功能描述區後是一個空行，接着是詳細說明區 ,

這部分主要是詳細說明你的 API 的功能，用途，如果可能，也可以有用法舉例等等。


Long Description

/** * - unordered item A * - unordered item B * * 1 ordered item A * 2 ordered item B */


Long Description

無長度限制可以多行一些 HTML 標籤使用

b, code, br, i, kbd, li, ol, p, pre, samp, ul, var


Tags

位於 Long Description 後一個空白行指明一些參數上的訊息，主要是

參數類型回傳值類型繼承聯系


@author aurthorname <[email protected]>

@author

描述作者 E - mail 可以怱略


@license

顯示版權及 URL 例：

@license http://opensource.org/licenses/api/licenese.php GUN Public License

@license authorname <[email protected]>

http://opensource.org/licenses/api/licenese.php

http://opensource.org/licenses/api/licenese.php


@package

出此檔是屬於哪個 package ， package 的名字和程式沒有關係，可以自由指定。指定它的用途只是方便管理檔案，讓相關的檔案在產生的註解文件中可以放一起呈現。


@param

變數及型態的說明 PHP 內的類型提示 (Type Hinting) 例：

@param int $num@param bool|string $foo a bool or string

param

@param datatype $paramname description


@return

函數回傳表示回傳值的型態例：

@return mixed@return fooClass|false fooClass object or

error

@return datatype descript


DocBlock Template

解決當重覆的列出相同的變數與方法許多遍時，造成的不良

這樣的情況叫 DocBlock Template


DocBlock Template /**#@+

* @access private* @var string*/

var $_var1 = ‘Hello’;var $_var2 = ‘World’;...var $_varN;/**#@-*/

// 下面的說明，不適用var $varX = array();


說明檔的產生 phpdoc -o HTML:frames:earthli -f

sample1.php -t docs


Option

-d ：指定的產生目錄中的代碼-t ：指定目標的文件-o ：輸出格式，指定模板


Template

你可以自己 / 選擇輸出格式 HTML - Smart CHM - Windows help 的模板可 PDF - Adobe Acrobat 形式 XML ： DocBook 的 - 可重複使用為出

發


PHPDocument 是從你原始碼的註釋中生成文檔，因此在在你程式中做註釋的流程，也就是你編製文檔的流程。

促使養成良好的編程習慣，盡量運用規範，清晰的文字為程式做註釋，同時多多少少也防止了事後編製文檔和文檔的更新不同步的一些問題。


更多資訊 http://www.phpdoc.org http://manual.phpdoc.org/HTMLSmartyC

onverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html

http://www.phpdoc.org/

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html




感謝大家結束

php documentor

Technology