• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Php documentor
 

Php documentor

on

  • 367 views

 

Statistics

Views

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