Php documentor
Upcoming SlideShare
Loading in...5
×
 

Php documentor

on

  • 428 views

 

Statistics

Views

Total Views
428
Views on SlideShare
428
Embed Views
0

Actions

Likes
0
Downloads
2
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

Php documentor Php documentor Presentation Transcript

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