如何在Eclipse中使用PHPdoc

Question

我们目前在一个新项目的开始，并希望(一次)从一开始就尽可能多地评论，以帮助未来的发展。

我试图找出在Eclipse中使用phpDoc的最佳实践是什么，但结果非常有限。

您能分享一下您在Eclipse中使用phpDoc注释内容的最佳实践和技巧吗？

Answer 1

关于应该注释什么以及如何注释，没有“真正的标准”，但几乎所有注释他的代码的人都会使用一些标记。

例如，我通常至少使用：

对于functions/methods

• @returns type的参数:对于functions/methods

• @throws ExceptionType的返回值:如果函数/方法在某些circumstances

• @see ...下抛出异常，则
• a short for a long description
• @param type name description：：当我想引用另一个文件，或者一个提供项目结构更多informations
• depending的网址时，我也可以使用Doctrine和@subpackage
• Another。当你在一个类中有魔术属性时(它们是用代码编写的，你的@package看不到它们)是@property type $name：它允许Eclipse PDT自动完成，甚至在魔术属性上也是如此--例如，Doctrine就是这样使用的。

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)

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

Answer 2

至少，我至少会坚持使用Eclipse根据您的代码自动插入的最小phpdoc标记。

我力争达到的第二个最低标准是让PhpDocumentor本身保持快乐。对代码运行PhpDocumentor后，在文档的根目录中查找errors.html页面。这将列出PhpDocumentor不喜欢的任何内容，例如没有文件级文档块。您可以努力将该错误列表降至零。

您可以努力达到的第三个级别是满足PEAR 1的PHP_CodeSniffer应用程序中包含的任何一种编码标准。这里的一个缺点是，这些标准更具体地关注代码本身，但所有标准都包含有关代码文档的规则。

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