Php documentor

604 views
570 views

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
604
On SlideShare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
3
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Php documentor

  1. 1. phpDocumentor<br />使用及方法簡要<br />Cloud<br />2011 Aircamel Copyright <br />1<br />
  2. 2. 文件的重要 <br />“Writing good documentation is essential to the success of any software project.”http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.pkg.html<br />特別是 OOS 項目<br />2011 Aircamel Copyright <br />2<br />
  3. 3. 文件的類型<br />Client User<br />教學或使用文件<br />開發人員<br />案例:API文檔<br />2011 Aircamel Copyright <br />3<br />
  4. 4. What’s phpDocumentor<br />HPDocumentor是一個用PHP寫的工具,對於有規範註釋的php程式。<br />它能夠快速生成具有相互參照,索引等功能的API文檔。<br />可以通過在客戶端瀏覽器上操作生成文檔,文檔可以轉換為PDF,HTML,CHM幾種形式,非常的方便。<br />2011 Aircamel Copyright <br />4<br />
  5. 5. How’s Work<br />掃描指定目錄下面的php原始碼,掃描其中的關鍵字,截取須要分析的註釋,然後分析註釋中的專用的tag,生成 xml文件<br />接着根據已經分析完的類別和區塊的訊息,建立相應的索引,生成xml文件<br />對於生成的xml文件,運用定制的模板輸出為指定格式的文件 <br />2011 Aircamel Copyright <br />5<br />
  6. 6. Example<br />PEAR API Documentation<br />http://pear.php.net/package/Auth/docs/latest/<br />Zend Framework<br />http://framework.zend.com/apidoc/core<br />symfony<br />http://www.symfony-project.org/api/1_2<br />2011 Aircamel Copyright <br />6<br />
  7. 7. How to Install<br />phpDocumentor的安裝分為自動安裝和手動安裝兩種方式<br />通過pear 自動安裝pear install PhpDocumentor<br />手動安裝在http://manual.phpdoc.org/下載最新版本的PhpDocumentor把內容解壓即可。 <br />2011 Aircamel Copyright <br />7<br />
  8. 8. 如何使用<br />所有的註釋都是由/**開始的一個多行註釋,在phpDocumentor裡稱為DocBlock, DocBlock是指軟體開發人員編寫的關於某個關鍵字的幫助訊息,使得 其他人能夠通過它知道這個關鍵字的具體用途,如何運用 。<br />PhpDocumentor規定 一個DocBlock包含如下訊息:<br />功能簡述區 (Short Description)<br />詳細說明區 (Long Description)<br />標記tag <br />2011 Aircamel Copyright <br />8<br />
  9. 9. DocBlock<br />/*** Short description ** Long description. This is an sample function * to show the DocBlock format.** 2nd paragraph of long description. * * * @tag1 * @tag2 */<br />2011 Aircamel Copyright <br />9<br />
  10. 10. Short Description<br />正文一般是簡明扼要地說明這個類別,方法或者 函數的功能。<br />功能簡述的正文在生成的文檔中將顯示在索引區。<br />功能描述區的內容可 以通過一個空行或者 */ 來 結束。<br />2011 Aircamel Copyright <br />10<br />
  11. 11. Long Description<br />在功能描述區後是一個空行,接着是詳細說明區,<br />這部分主要是詳細說明你的API的 功能,用途,如果可能,也可以有用法舉例等等。<br />2011 Aircamel Copyright <br />11<br />
  12. 12. Long Description<br />/*** - unordered item A * - unordered item B * * 1 ordered item A * 2 ordered item B */<br />2011 Aircamel Copyright <br />12<br />
  13. 13. Long Description<br />無長度限制<br />可以多行<br />一些HTML標籤使用<br /> b, code, br, i, kbd, li, ol, p, pre, samp, ul, var<br />2011 Aircamel Copyright <br />13<br />
  14. 14. Tags<br />位於Long Description 後一個空白行<br />指明一些參數上的訊息,主要是<br />參數類型<br />回傳值<br />類型<br />繼承聯系<br />2011 Aircamel Copyright <br />14<br />
  15. 15. @author<br />@author aurthorname<name@example.com><br />描述作者<br />E - mail 可以怱略<br />2011 Aircamel Copyright <br />15<br />
  16. 16. @license<br />顯示版權及 URL<br />例:<br />@license http://opensource.org/licenses/api/licenese.php GUN Public License<br />2011 Aircamel Copyright <br />16<br />@license authorname<name@example.com><br />
  17. 17. @package<br />出此檔是屬於哪個 package , package 的名字和程式沒有關係,可以自由指定。指定它的用途只是方便管理檔案,讓相關的檔案在產生的註解文件中可以放一起呈現。<br />2011 Aircamel Copyright <br />17<br />
  18. 18. @param<br />變數及型態的說明<br />PHP 內的類型提示(Type Hinting)<br />例:<br />@paramint $num<br />@parambool|string $foo a bool or string param<br />2011 Aircamel Copyright <br />18<br />@paramdatatype$paramnamedescription<br />
  19. 19. @return<br />函數回傳表示<br />回傳值的型態<br />例:<br />@return mixed<br />@return fooClass|falsefooClass object or error<br />2011 Aircamel Copyright <br />19<br />@return datatypedescript<br />
  20. 20. DocBlock Template<br />解決當重覆的列出相同的變數與方法許多遍時,造成的不良<br />這樣的情況叫DocBlock Template<br />2011 Aircamel Copyright <br />20<br />
  21. 21. DocBlock Template<br />/**#@+* @access private* @var string*/var $_var1 = ‘Hello’;var $_var2 = ‘World’;...var $_varN;/**#@-*///下面的說明,不適用var $varX = array();<br />2011 Aircamel Copyright <br />21<br />
  22. 22. 說明檔的產生<br />phpdoc-o HTML:frames:earthli -f sample1.php -t docs<br />2011 Aircamel Copyright <br />22<br />
  23. 23. Option<br />-d:指定的產生目錄中的代碼-t :指定目標的文件-o:輸出格式,指定模板<br />2011 Aircamel Copyright <br />23<br />
  24. 24. Template<br />你可以自己/選擇輸出格式<br />HTML - Smart<br />CHM - Windows help 的模板可<br />PDF - Adobe Acrobat 形式<br />XML:DocBook的 - 可重複使用為出發<br />2011 Aircamel Copyright <br />24<br />
  25. 25. PHPDocument是從你原始碼的註釋中生成文檔,因此在在你程式中做註釋的流程 ,也就是你編製文檔的流程 。<br />促使養成良好的編程習慣,盡量運用規範,清晰的文字為程式做註釋,同時多多少少也防止 了事後編製文檔和文檔的更新不同步的一些問題。<br />2011 Aircamel Copyright <br />25<br />
  26. 26. 更多資訊<br />http://www.phpdoc.org<br />http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html<br />2011 Aircamel Copyright <br />26<br />
  27. 27. 感謝大家<br />結束<br />2011 Aircamel Copyright <br />27<br />

×