正確的DocBlock注釋類的方法，它實現工廠設計模式

Question

正確的DocBlock評論的意思是評論：

• 符合PHPDoc標准

• 提供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層次結構如下所示：

我為@return標記提供了M_UserObject|M_TransactionObject類型描述。 它為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 ，這是一個可怕的名字）。 所以我只需將返回類型提示標記為CoreObject並完成它。

處理類似這樣的事情的首選方法是使用接口，並讓您的方法返回該接口的實現。 如果您沒有所有返回類型的公共接口，那么您需要實現不同的方法（至少或可能不同的工廠）。

Answer 2

目前不可能。

觀看此門票以了解它何時實施：http： //youtrack.jetbrains.com/issue/WI-6027

如果你不想為每個類都有單獨的方法，那么我可能只建議對局部變量使用PHPDoc @var注釋 （這可能非常不方便 - 取決於你如何使用它）：

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

Answer 3

建議的方法是首先放置常規類型（如果您的Factory創建特定類型的子類型，而不是類型），然后您可以添加所有子類型（或重要的子類型）。

這通常對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[]

第一種類型表示已定義的用途（例如，最后一行是IteratorAggregate getIterator() ），替代類型對於解決IDE-Typehinting的缺陷很有用（PHPStorm從來都不是很好用）。

HTH。 @ircmaxell所寫的內容並沒有錯，但是如果你為他的意思留下第一個返回類型（接口去那里），只要你理解替代類型僅用於類型提示，你就沒問題。 如果工廠方法返回許多不同的“類型”，則所有這些應該共享一個接口。 這個很重要。 例如，如果您看到長列表，則應該有一種類型，並且一種類型是接口。