如何在Eclipse中使用PHPdoc

Question

我們目前正處於一個新項目的開始階段，希望儘可能從一開始就對未來發展提出意見。

我試圖找出哪些最佳做法是在Eclipse中使用phpDoc，但結果相當渺茫。

你可以分享你的最佳實踐和使用phpDoc在Eclipse中評論的東西的技巧？

Answer 1

關於應該評論什麼以及如何評論，沒有「真正的標準」，但幾乎所有評論他的代碼的人都使用了一些標籤。

例如，我一般使用至少：

• 一個簡短描述
• optionnally，長描述
• @param type name description：爲功能/方法
• @returns type的參數：用於返回函數/方法的值
• @throws ExceptionType：如果函數/方法在某些情況下拋出異常
• @see ..。 ：當我想對任何其他文件，或者根據項目的結構，讓更多的信息
• 的URL的引用，我也可以用@package和@subpackage
• 另外一個說的真好當你有魔法屬性在類中（它們不能在您的IDE中看到，因爲它們是在代碼中編寫的）是@property type $name：它允許Eclipse PDT自動完成，即使在魔術屬性上也是如此 - 例如Doctrine使用它。

大多數那些的Eclipse PDT中使用的編碼時幫你（特別是@param）;但可以隨意添加一些Eclipse PDT未使用的代碼：如果從代碼生成文檔，它可以始終有用;-)

我可以給你的最好建議是看一看在一些大型應用程序和/或框架（Zend Framework，Doctrine，...）的源代碼中，看看他們的代碼是如何評論的 - 他們很可能正在使用被廣泛接受的東西。

舉例來說，如果你看看Zend框架的代碼，你可以找到這樣的東西一類：

/** 
* @package Zend_Cache 
* @subpackage Zend_Cache_Backend 
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) 
* @license http://framework.zend.com/license/new-bsd  New BSD License 
*/ 
class Zend_Cache_Backend_Apc extends Zend_Cache_Backend implements Zend_Cache_Backend_ExtendedInterface 

而且像這樣的方法：

/** 
* Test if a cache is available for the given id and (if yes) return it (false else) 
* 
* WARNING $doNotTestCacheValidity=true is unsupported by the Apc backend 
* 
* @param string $id      cache id 
* @param boolean $doNotTestCacheValidity if set to true, the cache validity won't be tested 
* @return string cached datas (or false) 
*/ 
public function load($id, $doNotTestCacheValidity = false) 

無論如何，最重要的是要保持一致：您團隊的每個成員都應該以同樣的方式發表評論，遵循相同的約定。

Answer 2

至少我會堅持最小的phpdoc標記是由Eclipse根據您的代碼自動插入的。

我努力爭取的第二個最低水平將是保持PhpDocumentor本身的快樂。一旦針對您的代碼運行PhpDocumentor，請查找文檔根目錄下的errors.html頁面。這將列出PhpDocumentor不喜歡的任何內容，例如沒有文件級別的文檔塊。您可以努力將錯誤列表降至零。

您可以努力達到的第三個級別將滿足PEAR [1]中PHP_CodeSniffer應用程序中包含的任何一種編碼標準。這裏的一個缺點是這些標準更專注於代碼本身，但是所有標準都包含有關代碼文檔的規則。

[1] - http://pear.php.net/package/PHP_CodeSniffer