如何在Eclipse中使用PHPdoc

Question

我们目前正处于一个新项目的开始阶段,并且希望(从一开始)尽可能多地评论从一开始就帮助未来的发展.

我试图找出在Eclipse中使用phpDoc的最佳实践,但结果非常简洁.

您能否分享使用phpDoc在Eclipse中评论内容的最佳实践和技巧？

Answer 1

关于应该评论什么以及如何评论没有"真正的标准",但是几乎所有评论他的代码的人都使用了一些标签.

例如,我通常至少使用:

• 简短说明
• 可选地,长描述
• @param type name description :用于函数/方法的参数
• @returns type :for函数/方法的返回值
• @throws ExceptionType :如果函数/方法在某些情况下抛出异常
• @see ...:当我想要引用另一个文件或提供更多信息的URL时
• 根据项目的结构,我也可以使用@package和@subpackage
• 另外一个,很高兴,当你在一个类魔法属性(他们不能在你的IDE中可以看出,因为它们都写在代码)是@property type $name:它使Eclipse PDT做自动完成,甚至在魔法属性-学说使用此, 例如.

Eclipse PDT使用它们中的大多数来帮助您编写代码(特别是@param) ; 但是随意添加一些Eclipse PDT不使用的内容:如果从代码生成文档,它总是有用的;-)

我能给你的最好的建议是看看一些大的应用程序和/或框架的源代码(Zend Framework,Doctrine,...),看看他们的代码是如何评论的 - 很可能是他们的使用被广泛接受的东西.

例如,如果你看一下Zend Framework代码,你可以在类中找到这样的东西:

/**
 * @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)

无论如何,最重要的是要保持一致:团队中的每个成员都应该以相同的方式发表评论,遵循相同的惯例.