如何在 Eclipse 中使用 PHPdoc答案

【问题标题】：How to use PHPdoc in Eclipse如何在 Eclipse 中使用 PHPdoc
【发布时间】：2011-01-19 08:20:48
【问题描述】：

我们目前正处于一个新项目的开始阶段，并希望（一次）从一开始就尽可能多地发表评论，以帮助未来的发展。

我试图找出在 Eclipse 中使用 phpDoc 的最佳实践，但结果相当渺茫。

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

【问题讨论】：

标签： php eclipse ide phpdoc

【解决方案1】：

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

例如，我通常至少使用：

简短说明
（可选）长描述
@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 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)

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

【讨论】：

感谢您的广泛回复。非常感激。我将使用它并研究如何设置一些评论标准！
为@property +1。我们一直在寻找一种让动态属性更加明显的方法

【解决方案2】：

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

我要争取的第二个最低级别是让 PhpDocumentor 自己开心。对代码运行 PhpDocumentor 后，在文档的根目录中查找 errors.html 页面。这将列出任何 PhpDocumentor 不喜欢的内容，例如没有文件级文档块。您可以努力将错误列表减少到零。

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

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

【讨论】：