如何在Eclipse中使用PHPdoc [英] How to use PHPdoc in Eclipse

问题描述

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

We are currently in the beginning of a new project, and would like to (for once) comment as much as possible from the start to help future development.

我试图找出在Eclipse中使用phpDoc的最佳做法，但结果非常细腻。

I have tried to find out what best practices are of using phpDoc in Eclipse, but with pretty slim results.

您能分享使用phpDoc评论的最佳做法和技巧东西在Eclipse中？

Can you share your best practices and tricks of using phpDoc to comment stuff in Eclipse?

推荐答案

没有关于应该注释什么的方式的真正标准几乎任何人评论他的代码。

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 :

• 简短描述


• 选项，长描述


• @param类型名称描述：对于函数/方法的参数


• @returns类型：用于函数/方法的返回值


• @throws ExceptionType ：如果函数/方法抛出在某些情况下例外


• @see .. 。 ：当我想要引用另一个文件或者提供更多信息的URL


• 取决于项目的结构时，我也可以使用 @包和 @subpackage


• 另一个很好，当你有类中的魔术属性 （它们不能被IDE看到，因为它们是在代码中编写的）是 @property type $ name ：它允许Eclipse PDT自动完成，甚至在魔法属性 - 例如，Doctrine使用这个。

• 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.

Eclipse PDT大多数使用它来帮助你编码（特别是 @param ）;但是请随意添加一些Eclipse PDT不使用的代码：如果您从代码生成文档，则始终可以使用; - ）

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 ;-)

我可以给你的最好的建议是看一些大型应用程序和/或框架（Zend Framework，Doctrine，...）的源代码，看看如何他们的代码被评论了 - 他们正在使用的东西很受欢迎。

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.

例如，如果你看看Zend Framework代码，你可以找到这样的东西一个类：

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

像这样一个方法： / p>

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.

这篇关于如何在Eclipse中使用PHPdoc的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！