1. phpDocumentor 使用及方法簡要 Cloud 2011 Aircamel Copyright 1

2. 文件的重要 “Writing good documentation is essential to the success of any software project.”http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.pkg.html 特別是 OOS 項目 2011 Aircamel Copyright 2

3. 文件的類型 Client User 教學或使用文件 開發人員 案例：API文檔 2011 Aircamel Copyright 3

4. What’s phpDocumentor HPDocumentor是一個用PHP寫的工具，對於有規範註釋的php程式。 它能夠快速生成具有相互參照,索引等功能的API文檔。 可以通過在客戶端瀏覽器上操作生成文檔，文檔可以轉換為PDF,HTML,CHM幾種形式，非常的方便。 2011 Aircamel Copyright 4

5. How’s Work 掃描指定目錄下面的php原始碼，掃描其中的關鍵字，截取須要分析的註釋，然後分析註釋中的專用的tag，生成 xml文件 接着根據已經分析完的類別和區塊的訊息，建立相應的索引，生成xml文件 對於生成的xml文件，運用定制的模板輸出為指定格式的文件 2011 Aircamel Copyright 5

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 6

7. How to Install phpDocumentor的安裝分為自動安裝和手動安裝兩種方式 通過pear 自動安裝pear install PhpDocumentor 手動安裝在http://manual.phpdoc.org/下載最新版本的PhpDocumentor把內容解壓即可。 2011 Aircamel Copyright 7

8. 如何使用 所有的註釋都是由/**開始的一個多行註釋，在phpDocumentor裡稱為DocBlock, DocBlock是指軟體開發人員編寫的關於某個關鍵字的幫助訊息，使得 其他人能夠通過它知道這個關鍵字的具體用途，如何運用 。 PhpDocumentor規定 一個DocBlock包含如下訊息： 功能簡述區 (Short Description) 詳細說明區 (Long Description) 標記tag 2011 Aircamel Copyright 8

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

10. Short Description 正文一般是簡明扼要地說明這個類別，方法或者 函數的功能。 功能簡述的正文在生成的文檔中將顯示在索引區。 功能描述區的內容可 以通過一個空行或者 */ 來 結束。 2011 Aircamel Copyright 10

11. Long Description 在功能描述區後是一個空行，接着是詳細說明區, 這部分主要是詳細說明你的API的 功能，用途，如果可能，也可以有用法舉例等等。 2011 Aircamel Copyright 11

12. Long Description /*** - unordered item A * - unordered item B * * 1 ordered item A * 2 ordered item B */ 2011 Aircamel Copyright 12

13. Long Description 無長度限制 可以多行 一些HTML標籤使用 b, code, br, i, kbd, li, ol, p, pre, samp, ul, var 2011 Aircamel Copyright 13

14. Tags 位於Long Description 後一個空白行 指明一些參數上的訊息，主要是 參數類型 回傳值 類型 繼承聯系 2011 Aircamel Copyright 14

15. @author @author aurthorname<name@example.com> 描述作者 E - mail 可以怱略 2011 Aircamel Copyright 15

16. @license 顯示版權及 URL 例： @license http://opensource.org/licenses/api/licenese.php GUN Public License 2011 Aircamel Copyright 16 @license authorname<name@example.com>

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

18. @param 變數及型態的說明 PHP 內的類型提示(Type Hinting) 例： @paramint $num @parambool|string $foo a bool or string param 2011 Aircamel Copyright 18 @paramdatatype$paramnamedescription

19. @return 函數回傳表示 回傳值的型態 例： @return mixed @return fooClass|falsefooClass object or error 2011 Aircamel Copyright 19 @return datatypedescript

20. DocBlock Template 解決當重覆的列出相同的變數與方法許多遍時，造成的不良 這樣的情況叫DocBlock Template 2011 Aircamel Copyright 20

21. DocBlock Template /**#@+* @access private* @var string*/var $_var1 = ‘Hello’;var $_var2 = ‘World’;...var $_varN;/**#@-*///下面的說明，不適用var $varX = array(); 2011 Aircamel Copyright 21

22. 說明檔的產生 phpdoc-o HTML:frames:earthli -f sample1.php -t docs 2011 Aircamel Copyright 22

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

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

25. PHPDocument是從你原始碼的註釋中生成文檔，因此在在你程式中做註釋的流程 ，也就是你編製文檔的流程 。 促使養成良好的編程習慣，盡量運用規範，清晰的文字為程式做註釋，同時多多少少也防止 了事後編製文檔和文檔的更新不同步的一些問題。 2011 Aircamel Copyright 25

26. 更多資訊 http://www.phpdoc.org http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html 2011 Aircamel Copyright 26

27. 感謝大家 結束 2011 Aircamel Copyright 27