正确的DocBlock注释类的方法,它实现工厂设计模式

时间:2013-03-25 11:49:05

标签: php oop autocomplete phpstorm phpdoc

正确的DocBlock评论的含义是:

这是班级本身:

class Factory_DomainObjects
{
    /**
     * Build domain object
     *
     * @param $name
     *
     * @return M_UserObject|M_TransactionObject
     */
    public function build($name)
    {
        $class = 'M_' . $name . 'Object';
        return new $class();
    }
}

它根据Core_Object参数从$name层次结构中返回一个对象。

目前Core_Object层次结构如下所示:
enter image description here

我为@return标记提供了M_UserObject|M_TransactionObject类型说明。它为PHPStorm提供自动操作,并符合PHPdoc标准。

- 但这正是你想要的,问题是什么?
- 是和否,请继续阅读:)

问题
如果Core_Object层次结构会变成这样的结果怎么办? enter image description here

这会将@return标记说明变成混乱:

/**
 * @return M_TransactionObject|M_UserObject|M_Foo|M_Foo1|M_Foo2|M_Foo3|M_Bar|M_Bar1|M_Bar2|M_Bar3
 */

到目前为止我找到的唯一解决方法:为每个对象使用单独的build方法,即

/**
 * Build user domain object
 * 
 * @return M_UserObject
 */
public function buildUser()
{
    return new M_UserObject();
}

/**
 * Build transaction domain object
 * 
 * @return M_TransactionObject
 */
public function buildTransaction()
{
    return new M_TransactionObject();
}

您认为我的解决方法有哪些陷阱?你会建议什么?

3 个答案:

答案 0 :(得分:6)

这里的简单答案是您不应该从单个方法返回多个对象类型。让我详细说明一下:

当我说“类型”时,我指的是并非都以某种方式共享相同类型信息的对象。在你的情况下,他们都是CoreObject(顺便说一句,这是一个可怕的名称)。所以我只需将返回类型提示标记为CoreObject并完成它。

处理类似这样的事情的首选方法是使用接口,并让您的方法返回该接口的实现。如果您没有所有返回类型的公共接口,那么您需要实现不同的方法(至少或可能不同的工厂)。

答案 1 :(得分:1)

目前无法实现。

观看此故障单,了解它的实施时间:http://youtrack.jetbrains.com/issue/WI-6027

如果您不希望每个类都有单独的方法,那么我可能只建议使用 PHPDoc @var注释用于局部变量(这可能非常不方便 - 取决于您的使用方式它):

/** @var M_FooObject $myFoo */
$myFoo = $factory->build('Foo');

答案 2 :(得分:1)

建议的方法是首先放置常规类型(如果您的工厂创建特定类型的子类型,而不是类型),然后您可以添加所有子类型(或重要类型)。

这通常对PHPStorm非常有用,并且完全没有违反PHPDoc。

/**
 * @return M_TransactionObject|M_UserObject|M_Foo|M_Foo1|M_Foo2|M_Foo3|M_Bar|M_Bar1|M_Bar2|M_Bar3
 */

这太过分了。我通常使用 @return 标签不超过三种(子)类型。我会说这是一个很好的经验法则。

例如:

 * @return M_UserObject|M_TransactionObject

在我眼里是可以的。一个类似的提示 - 移动是:

 * @return array|string[]

* @return Iterator|string[]

第一种类型表示已定义的用法(例如最后一行是getIterator()的{​​{1}}),替代类型对于解决IDE-Typehinting的缺陷很有用(PHPStorm从来没有那么简单)这很好。)

HTH。 @ircmaxell所写的内容并没有错,但是如果你为他的意思留下第一个返回类型(接口去那里),只要你理解替代类型仅用于类型提示,你就没问题。如果工厂方法返回许多不同的“类型”,则所有这些应该共享一个接口。这个很重要。例如,如果您看到长列表,则应该有一种类型,并且一种类型是接口。