熱點推薦:
您现在的位置: 電腦知識網 >> 編程 >> PHP編程 >> 正文

關於PHPDocument 代碼注釋規范的總結

2013-11-15 12:38:34  來源: PHP編程 

   安裝phpDocumentor(不推薦命令行安裝)
在下載最新版本的PhpDoc
放在web服務器目錄下使得通過浏覽器可以訪問到
點擊files按鈕選擇要處理的php文件或文件夾
還可以通過該指定該界面下的Files to ignore來忽略對某些文件的處理
然後點擊output按鈕來選擇生成文檔的存放路徑和格式
最後點擊createphpdocumentor就會自動開始生成文檔了

  .如何寫PHP規范注釋
所有的文檔標記都是在每一行的 * 後面以@開頭如果在一段話的中間出來@的標記這個標記將會被當做普通內容而被忽略掉
@access 該標記用於指明關鍵字的存取權限privatepublic或proteced 使用范圍classfunctionvardefinemodule
@author 指明作者
@copyright 指明版權信息
@const 使用范圍define 用來指明php中define的常量
@final 使用范圍classfunctionvar 指明關鍵字是一個最終的類方法屬性禁止派生修改
@global 指明在此函數中引用的全局變量
@name 為關鍵字指定一個別名
@package 用於邏輯上將一個或幾個關鍵字分到一組
@abstrcut 說明當前類是一個抽象類
@param 指明一個函數的參數
@return 指明一個方法或函數的返回值
@static 指明關建字是靜態的
@var 指明變量類型
@version 指明版本信息
@todo 指明應該改進或沒有實現的地方
@link 可以通過link指到文檔中的任何一個關鍵字
@ingore 用於在文檔中忽略指定的關鍵字

  一些注釋規范
a注釋必須是
/**
* XXXXXXX
*/
的形式
b對於引用了全局變量的函數必須使用glboal標記
c對於變量必須用var標記其類型(intstringbool
d函數必須通過param和return標記指明其參數和返回值
e對於出現兩次或兩次以上的關鍵字要通過ingore忽略掉多余的只保留一個即可
f調用了其他函數或類的地方要使用link或其他標記鏈接到相應的部分便於文檔的閱讀
g必要的地方使用非文檔性注釋(PHPDOC無法識別的關鍵字前的注釋)提高代碼易讀性
h描述性內容盡量簡明扼要盡可能使用短語而非句子
i全局變量靜態變量和常量必須用相應標記說明

  能夠被phpdoc識別的關鍵字
Include
Require
include_once
require_once
define
function
global
class

   規范注釋的php代碼 :
<?php
/**
* 文件名(samplephp)
*
* 功能描述(略)
*
* @author steve <
* @version
* @package sample
*/
/**
* 包含文件
*/
include_once samplephp;
/**
* 聲明全局變量
* @global integer $GLOBALS[_myvar]
* @name $_myvar
*/
$GLOBALS[_myvar] = ;
/**
* 聲明全局常量
*/
define(NUM );
/**
* 類名
*
* 類功能描述
*
* @package sample
* @subpackage classes(如果是父類 就添加)
*/
class myclass {
/**
* 聲明普通變量
*
* @accessprivate
* @var integer|string
*/
var $firstvar = ;
/**
* 創建構造函數 {@link $firstvar}
*/
function myclass() {
$this>firstvar = ;
}
/**
* 定義函數
*
* 函數功能描述
*
* @global string $_myvar
* @staticvar integer $staticvar
* @param string $param
* @param string $param
* @return integer|string
*/
function firstFunc($param $param = optional) {
static $staticvar = ;
global $_myvar;
return $staticvar;
}
}
?>


From:http://tw.wingwit.com/Article/program/PHP/201311/21335.html
    推薦文章
    Copyright © 2005-2013 電腦知識網 Computer Knowledge   All rights reserved.