如何记录来自另一种方法的返回类型？答案

【问题标题】：How do I document the return type which comes from another method?如何记录来自另一种方法的返回类型？
【发布时间】：2018-07-06 01:35:36
【问题描述】：

当一个方法返回对另一个方法的调用结果时，记录返回类型的明智方法是什么？

class A
{
    /**
     * @return [How do I know here what bar will return?]
     */
    public function foo()
    {
        $b = new B();
        return $b->bar();
    }
}

class B
{
    /**
     * @return string
     */
    public function bar()
    {
        return 'baz';
    }
}

当不确定B::baz() 会返回什么时，如何记录A::foo() 返回类型？将来B::baz() 可能会发生变化，在这种情况下A::foo() 的返回类型会在不知不觉中发生变化。

这是代码异味吗？是否可以设计更广泛的代码，使A::foo() 的返回类型即使B::baz() 发生变化也是可预测的？

【问题讨论】：

标签： php documentation phpdoc

【解决方案1】：

如果我们说的是更高的类型严格，你应该重构你的代码并告诉 bar() 将返回什么样的类型：(PHP >7.0)

class A
{
    /**
     * @return string
     */
    public function foo()
    {
        $b = new B();
        return $b->bar();
    }
}

class B
{
    /**
     * @return string
     */
    public function bar() : string
    {
        return 'baz';
    }
}

参考：http://php.net/manual/en/migration70.new-features.php

但在您的情况下，我会将 B\bar 作为返回类型，因为您返回的是类 B 和方法 bar 的实例。

         * @return B\bar
         */
        public function foo()
        {

【讨论】：

【解决方案2】：

如果您担心bar() 返回类型可能会改变而不管您的foo() 期望什么，那么我会说这确实是代码异味。两者之间显然没有合同，所以从A 到B 没有信任。

更实际地，bar()已记录以返回 string，因此通过将 foo() 编码为返回 bar() 的实际返回值，那么 foo() 也应记录为返回string。文档生成器/IDE 不会有自动方式来跟上这个为你，如果那是你所追求的。

另一个仅限文档的选项是将foo() 的返回标记为mixed，从而告诉读者“我不保证我返回的内容，因为我只给你bar() 给出的内容我，我不知道那会是什么”。

【讨论】：