如何文檔化你的PHP類(二)

如何文檔化你的PHP類(二)

[br]
作者：stefano Locati 翻譯：limodou  

文檔化函數或方法  
　　成員函數或方法使用@function標記被文檔化。  

--------------------------------------------------------------------------------  
/*! @function getItemingroup  
    @abstract gets a bagitem of a given group and a given position  
    @param groupno int - the delivery group ordinal position in the bag  
    @param pos     int - the position of the bagitem within the group  
    @result Object - the BagItem in a given position of given group  
or -1 if it could not be found  
*/  
--------------------------------------------------------------------------------  

文檔化一個方法。  

　　@function標記聲明了一個函數並且後面跟著函數或成員函數名。然後你可以象前面一樣使用 @abstract和@discussion標記。然而還有兩個額外的標記。@param標記用於描述函數的參數；第一個詞假設為變數的名字，其它的則為任意的文本描述。我建議要聲明想要的變數類型，儘管PHP不是一個強型別語言。 @result標記被用於描述傳回值。  

文檔化變數  
　　變數或類變數都使用@var標記來描述。在這個標記中，第一個詞被認為是變數的名字，同時其它的則為任意的文本描述。象前面一樣，我建議寫出所期望的變數類型是好的做法。它也是一個文檔化所有類變數的好主意。  


文檔化一個類變數。  

--------------------------------------------------------------------------------  
/*! @var idsession   string - an unique session identifier */  
var $idsession;  
--------------------------------------------------------------------------------  
最後接觸  
--------------------------------------------------------------------------------  
/*! @header myprojectname  
    @abstract a virtual store to shop on mars  
    @discussion The difference [...]  
*/  
--------------------------------------------------------------------------------  
　　@header標記用來提供一些關於被文檔化的項目或類組的一般性資訊。@header標記本身跟著項目的名字 ，而且可以用@abstract標記和@discussion標記來補充說明。因為類通常存在於不同的檔案中（一個檔案一個類，且用類的名字給檔案名稱字是一種好的想法），你可能想知道應該將@header 標記放在什麼地方。答案很讓人吃驚，哪都可以。我的建議是：如果它比較長就把它放在一個獨立的檔案中，或如果是一個簡短的說明就把它放在最重要的類的前面。  

如何修改指令碼用於PHP  
　　從Apple得到的初始的HeaderDoc指令碼是用於C或C++標頭檔的，所以要用在PHP中需要對它做一些小改動 。如果你對細節沒有興趣，你可以從這裡下 載，並且跳過下面部分。
　　修改來源程式所做的唯一的事情就是在主perl檔案中，使指令碼可以接受.php和.php3尾碼。  

--------------------------------------------------------------------------------  
$ diff headerDoc2HTML.pl /usr/local/bin/headerdoc2html  
195c195  
<     ($rootFileName = $filename) =~ s/.(h|i)$//;  
---  
>     ($rootFileName = $filename) =~ s/.(h|i|php|php3)$//;  
--------------------------------------------------------------------------------  
運行指令碼  
　　在安裝完指令碼之後，假設你的類放在classes子目錄下，並且你想將產生的文檔放在docs目錄下，你應該執行這個命令：  

headerdoc2html -o docs classes/*.php  

　　不幸的是如果存在多個PHP檔案，這個指令碼有一個壞習慣就是將那些檔案分割到不同的目錄中去，使得在類的文檔中瀏覽變得很困難。而且因為初始的指令碼是為C/C++標頭檔所寫的（標頭檔中只有類和函數的聲明而沒有他們的定義），指令碼會將函數名下的所有代碼輸出，直到碰到";"，所以典型的就是代碼的第一行。  

　　但是在你好不容易讀到現在卻感到絕望之前，放鬆，因為我寫了一段簡單的指令碼來解決這兩個問題。  

--------------------------------------------------------------------------------  
cat classes/*.php | sed 's/ *{/;#{/g' | tr "#" "  
" > docs/all.php  
headerdoc2html -o docs docs/all.php  
rm docs/all.php  
--------------------------------------------------------------------------------  
　　如果你想知道為什麼我在這裡使用tr命令而不是都用sed來做，原因就是用在仍然用在RedHat 6.2上的sed 3.02版本不處理分行符號。應該替換成新的版本sed 3.02a。如果你對sed感興趣，可以看SED FAQ。  

　　祝你的文檔化工作好運！  

翻譯後話：  
　　由於這篇文章是在Linux環境下使用的，所以在windows下的使用可能會有問題。我會試一試，能想辦法就想了，實在想不出來也沒有辦法了。  

原作者：limodou  
來源：PHPX