Php documentor

  • 330 views
Uploaded on

 

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
330
On Slideshare
0
From Embeds
0
Number of Embeds
0

Actions

Shares
Downloads
2
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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