給php代碼添加規範的注釋phpDocumentor

給php代碼添加規範的注釋

更多參考 http://phpdoc.org/docs/latest/index.html

在phpdocumentor中，注釋分為文檔性注釋和非文檔性注釋。

所謂文檔性注釋，是那些放在特定關鍵字前面的多行注釋，特定關鍵字是指能夠被phpdoc分析的關鍵字，例如class，var等，具體的可參加附錄1.

那些沒有在關鍵字前面或者不規範的注釋就稱作非文檔性注釋，這些注釋将不會被phpdoc所分析，也不會出現在你産生的api文當中。

3.2如何書寫文檔性注釋:

所 有的文檔性注釋都是由

的形式

b.對于引用了全局變量的函數，必須使用glboal标記。

c.對于變量，必須用var标記其類型（int,string,bool...）

d.函數必須通過param和return标記指明其參數和傳回值

e.對于出現兩次或兩次以上的關鍵字，要通過ingore忽略掉多餘的，隻保留一個即可

f.調用了其他函數或類的地方，要使用link或其他标記連結到相應的部分，便于文檔的閱讀。

g.必要的地方使用非文檔性注釋，提高代碼易讀性。

h.描述性内容盡量簡明扼要，盡可能使用短語而非句子。

i.全局變量，靜态變量和常量必須用相應标記說明

<?php
/**
* @name 名字
* @abstract 申明變量/類/方法
* @access 指明這個變量、類、函數/方法的存取權限
* @author 函數作者的名字和郵箱位址
* @category  組織packages
* @copyright 指明版權資訊
* @const 指明常量
* @deprecate 指明不推薦或者是廢棄的資訊MyEclipse編碼設定
* @example 示例
* @exclude 指明目前的注釋将不進行分析，不出現在文擋中
* @final 指明這是一個最終的類、方法、屬性，禁止派生、修改。
* @global 指明在此函數中引用的全局變量
* @include 指明包含的檔案的資訊
* @link 定義線上連接配接
* @module 定義歸屬的子產品資訊
* @modulegroup 定義歸屬的子產品組
* @package 定義歸屬的包的資訊
* @param 定義函數或者方法的參數資訊
* @return 定義函數或者方法的傳回資訊
* @see 定義需要參考的函數、變量，并加入相應的超級連接配接。
* @since 指明該api函數或者方法是從哪個版本開始引入的
* @static 指明變量、類、函數是靜态的。
* @throws 指明此函數可能抛出的錯誤異常,極其發生的情況
* @todo 指明應該改進或沒有實作的地方
* @var 定義說明變量/屬性。
* @version 定義版本資訊
*/
function XXX($a){..}

           

　　

<?php
/**
* Sample File 2, phpDocumentor Quickstart
*
* This file demonstrates the rich information that can be included in
* in-code documentation through DocBlocks and tags.
* @author Greg Beaver <[email protected]>
* @version 1.0
* @package sample
*/
 
//PHP code
 
/**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional') {
    static $staticvar = 7;
    global $_myvar;
    return $staticvar;
}