为实现工厂设计模式的类的方法提供适当的 DocBlock 注释

Question

我所说的正确的 DocBlock 评论是指这样的评论：

• 符合PHPDoc standard

• 提供PHPStorm IDE自动完成

这是课程本身：

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

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

目前Core_Object 层次结构如下所示：

我提供了带有M_UserObject|M_TransactionObject 类型描述的@return 标签。为 PHPStorm 提供自动竞争功能，符合 PHPdoc 标准。

- 但这正是你想要的，有什么问题？
- 是也不是，继续阅读 :)

问题：
如果Core_Object 层次结构会发展到这样的程度怎么办？

这会使@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();
}

您认为我的解决方法存在哪些缺陷？你会建议什么？

Answer 1

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

当我说“类型”时，我的意思是对象并不都以某种方式共享相同的类型信息。在您的情况下，它们都是CoreObject（顺便说一句，这是一个可怕的名称）。所以我会简单地将返回类型提示标记为CoreObject 并完成它。

处理此类事情的首选方法是使用接口，并让您的方法返回该接口的实现。如果您没有针对所有返回类型的通用接口，那么您需要实现不同的方法（至少，或者可能是不同的工厂）。

Answer 2

目前不可能。

观看此票以了解何时实施：http://youtrack.jetbrains.com/issue/WI-6027

如果您不想为每个类使用单独的方法，那么我可能只建议将 PHPDoc @var cmets 用于局部变量（这可能非常不方便 - 取决于您的使用方式它）：

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

Answer 3

建议的方法是先放通用类型（如果你的工厂创建了特定类型的子类型，那么这就是类型），然后你可以添加所有子类型（或重要的子类型）。

这通常与 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() 的IteratorAggregate），替代类型对于解决IDE-Typehinting 的缺陷很有用（PHPStorm 永远不会少用这个)。

HTH。 @ircmaxell 写的没有错，但是如果您将第一个返回类型保留为他的意思（接口在那里），只要您了解替代类型仅用于类型提示，您就可以了。如果一个工厂方法返回许多不同的“类型”，所有这些都应该共享一个接口。这个很重要。例如，如果您看到一长串列表，则应该有一种类型，而这种类型就是接口。