NetBeans PHP中正确记录类的正确方法 [英] Proper Way to Document Class in Netbeans PHP

问题描述

出于易于维护以及IDE类自动完成和成员提示的原因，我在项目中使用了PHPDoc.给定这个示例类:

For reasons of ease of maintenance AND IDE class auto-completion and member hinting, I've used PHPDoc in my project. Given this example class:

class my_class {
    public $id;
    public $name;
    public $number;

    public function __construct() {
        //Do something
    }

    public function Rename($name) {
        $this->name = $name;
    }
}

我更愿意使用类文档本身来记录所有属性($id，$name和$number)，该类文档位于类声明之上，然后将方法的文档(如有必要)放在每个方法之上.这是我最终希望我的班级看起来像的样子:

I would prefer to document all properties ($id, $name and $number) with the class documentation itself, which is above the class declaration, and then place documentation for methods (if necessary) above each method. Here is what I ultimately want my class to look like:

/**
 * Represents an example class for Stackoverflow
 * 
 * @property int $id The id of the object
 * @property string $name The name of the object 
 * @property int $number The number of the object
 */
class my_class {
    public $id;
    public $name;
    public $number;

    public function __construct() {
        //Do something
    }

    /**
     * Renames the object
     * @param string $name Name to rename object
     */
    public function Rename($name) {
        $this->name = $name;
    }
}

这正是我更希望作为文档使用的内容，但是Netbeans的自动完成功能无法正确运行，因为它会两次列出每个属性.例如，如果我开始键入$my_class_object->i，则自动完成功能将列出两个$ id属性:一个在我的PHPDoc中描述，而另一个在"PHPDoc Not Found"中被描述为未知变量.

This is precisely what I prefer to have as documentation, however Netbeans' autocomplete fails to operate correctly, as it lists each property twice. For example, if I start typing $my_class_object->i the auto-complete will list two $id properties: one as described in my PHPDoc, and another is described as an unknown variable with "PHPDoc Not Found".

有一种解决方案可以解决Netbeans的问题-在每个属性上方添加一个@var PHPDoc块，但是我认为这不必要地使我的类混乱，尤其是我的一些具有10多个属性的类.

There is a solution that works to solve the Netbeans issue - add a @var PHPDoc block above each property, however I think it unnecessarily clutters up my class, especially some of my classes that have 10+ properties.

我的两个问题(干净的文档，正确的Netbeans提示)是否都有[良好]解决方案，还是我做错了?

Is there a [good] solution to both of my issues (clean doc, proper Netbeans hinting), or am I going about this incorrectly?

推荐答案

"property"标记专门用于"magic"属性，即那些实际上未出现在代码本身中的属性.这就是标记仅在类docblock中出现的关键原因.因此，我猜想从在代码中看不到"的角度来看，识别属性"标签的IDE可以这样做.当然，我可以理解这样的期望，即自动完成功能应该识别出这种属性的存在，并因此为您提供.但是，我敢打赌，IDE将坚持只使用代码本身来构建模型，并且仅使用docblock信息来补充它已经在代码中看到的元素.

The "property" tag is specifically and explicitly for "magic" properties, meaning any that don't actually appear in the code itself. That's the key reason why the tag occurs only in the class docblock. As such, I'm guessing IDEs that recognize the "property" tag do so from that "it's NOT seen in the code" perspective. Granted, I could understand an expectation that autocomplete should recognize the existence of such a property, and therefore make it available for you. However, my bet is that the IDEs will stick with using only the code itself to build a model, and only use docblock info to supplement the elements that it already sees in the code.

使用"var"标签是记录已编码"属性的一种正确方法.如果要最小化在所有属性上使用该标记所需的行，请使用单行docblock:

Using the "var" tag is the one proper way to document your "coded" properties. If you want to minimize the lines required in order to use that tag on all the properties, use a one-line docblock:

/** @var int */
public $id;

此外，您可以使用docblock模板来减少标签相似度适合您的代码的docblock:

Also, you could use the docblock template to cut down on docblocks, where tag similarity fits your code:

/** @var string */
public $name;

/**#@+ @var int */
public $id;
public $number;
/**#@-*/

在这个简短列表中，这似乎并没有节省太多，但是当有很多属性时，它确实有帮助.而且，它在方法周围也能很好地工作.

That doesn't seem like much savings in this short list, but it does help when there are lots of properties. Also, it works fine around methods.

这篇关于NetBeans PHP中正确记录类的正确方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！