当前位置：文江博客话题详情

如何在 Eclipse 中使用 PHPdoc

发布于 2024-08-22 04:27:27 字数 155 浏览 1 评论 0原文

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

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

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

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

疯狂的代价 2024-08-29 04:27:27

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

例如，我通常至少使用：

一个简短的描述
（可选），一个长描述
@param类型名称描述：用于函数/方法的参数
@returns类型：用于函数/方法的返回值
@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)

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

There is no "real standard" about what should be commented and how, but some tags are used by pretty much anyone who comments his code.

For instance, I generally use at least :

a short descriptions
optionnally, a long description
@param type name description : for the parameters of functions/methods
@returns type : for the return value of functions/methods
@throws ExceptionType : if the functions/methods throws an Exception under some circumstances
@see ... : when I want to make a reference to either another file, or an URL that gives more informations
depending of the structure of the project, I can also use @package and @subpackage
Another one that's nice when you have magic properties in a class (they cannot be seen by your IDE, as they are written in the code) is @property type $name : it allows Eclipse PDT to do auto-completion, even on magic properties -- Doctrine uses this, for instance.

Most of those are used by Eclipse PDT to help you when coding (especially @param) ; but feel free to add some that are not used by Eclipse PDT : if you generate the documentation from your code, it can always be useful ;-)

The best advice I can give you would be to take a look at the source-code of some big applications and/or frameworks (Zend Framework, Doctrine, ...), to see how their code is commented -- chances are they are using something that's well accepted.

For instance, if you take a look at Zend Framework code, you can find stuff like this for a class :

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

And like this for a method :

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

Anyway, the most important thing is to be consistent : every member of your team should comment the same way, follow the same conventions.

回复收藏 0 原文