覆盖 PHPDoc 中的返回类型答案

【问题标题】：override return type in PHPDoc覆盖 PHPDoc 中的返回类型
【发布时间】：2013-12-23 17:27:53
【问题描述】：

我有一个带有方法的类Abc（正文不重要）：

/**
 * @return SomeBaseClass
 */
function getAll() { ... }

在名为AbcChild 的Abc 的子类中，我只想重新定义返回类的类型，以便在Netbeans 中正确查看它。我可以不重新定义方法吗：

/**
 * @return SomeClass
 */
function getAll() { return parent::getAll(); }

【问题讨论】：

标签： phpdoc

【解决方案1】：

试试这样的：

/**
 * @method SomeClass getAll()
 */
class AbcChild
{
 // ....
}

More info about @method

【讨论】：

【解决方案2】：

不，因为您需要子方法代码本身才能让子文档块与之关联。如果您有 docblock 但没有方法代码，则 docblock 不会绑定到任何东西，因此不会产生任何效果。大多数人不喜欢修改他们的代码以适应 docblock 行为，尽管我从来没有真正打扰过这样做。

但是，您的另一个选择是调整父方法上的@return 标记，以便它列出您希望指示子方法可以返回的所有可能的返回类型。不过，这让我想知道……如果您实际上并没有覆盖方法本身，那么子类实际上如何返回与父类不同的类？我可以在脑海中看到这样做的方法，涉及包含不同类对象的类属性，但它们会让我觉得代码有异味;-)

如果子级本身没有方法覆盖代码，那么我会选择将所有可能的返回类型放在父级的@return 中。

【讨论】：

这不是解决方案。让我们考虑一下 Yii 方法 CActiveRecord::model()->find() - 它返回由 model() 给出的类型的对象数组（这并不精确，但对于示例来说已经足够好了）。在我自己的继承 CActiveRecord 的类中，我必须重写 model() 以返回正确的类名。因此，在使用MyModel::model()->find() 的代码中，我希望返回 MyModel 而不是默认的 CActiveRecord。当然我不会修改框架来添加我自己的类做docblock。
鉴于此，完成您所寻求的唯一方法确实是您展示但希望避免的方法覆盖。

【解决方案3】：

实际上我认为除了完全方法覆盖之外还有其他方法。您可以在扩展基本接口的子接口中更改 @return phpdoc 块。让我用代码解释一下我的意思：

interface EntityRepository
{
   /**
    * @return object
    */
    public function get($id);
    public function add($entity, $sync = false);
    public function remove($entity, $sync = false);
    // other methods common for custom repositories
}

interface ProjectRepository extends EntityRepository
{
   /**
    * @return Project
    */
    public function get($id);
}

这是您域的一部分。现在是从 Symfony 和 Doctrine 中获取的具体实现：

use Doctrine\ORM\EntityRepository;
use Model\Repository\EntityRepository as BaseEntityRepository;

abstract class DoctrineEntityRepository extends EntityRepository implements BaseEntityRepository
{
    public function get($id)
    {
        $entity = $this->find($id);
        if (!$entity) {
            throw new EntityNotFoundException();
        }

        return $entity;
    }

    public function add($entity, $sync = false)
    {
        // method implementation
    }
    public function remove($entity, $sync = false)
    {
        // method implementation
    }
}

use Model\Repository\ProjectRepository as BaseProjectRepository;

class ProjectRepository extends DoctrineEntityRepository implements BaseProjectRepository
{
    public function specificQueryForProjects()
    {
        // method implementation
    }
}

这样您就不必仅仅因为代码自动完成而重写子类中的方法。您只需扩展接口，让 API 的用户知道返回值已更改。

【讨论】：