如何格式化复杂返回值的PHPDoc注释

我有一个函数，它返回如下结构：

array('form' => $form, 'options' => $options)

如何在函数注释中正确设置此返回值的格式

我的猜测是：

@return array('form' => CForm, 'options' => array) ... comment ...

---

有什么建议吗？

可能有点过分了，但是您可以返回具有特定接口的对象，而不是常规数组。比如：

/**
 * @return ReturnObject
 */
public function yourMethod()
{
    return new ReturnObjectImpl( $theForm, $theOptions );
}

interface ReturnObject
{
    public function getCForm();
    public function getOptions();
}

class ReturnObjectImpl
    implements ReturnObject
{
    protected $_form;
    protected $_options;

    public function __construct( CForm $form, array $options )
    {
        $this->_form = $form;
        $this->_options = $options;
    }

    public function getCForm()
    {
        return $this->_form;
    }

    public function getOptions()
    {
        return $this->_options;
    }
}

---

当您必须返回一个奇怪的数组时，请简单易懂地记录它

我会这样做的。请随意使用

@returnarray

而不是

mixed[]

：

<?php
/**
 * Method to do something
 *
 * @param Some_User_Class $user
 * @param string $blockUserId
 * @throws Some_Model_Relations_ErrorException
 * @return mixed[] see example
 * @example The returned array consists of this
 *  and that and might have foo and bar.
 *  so this makes me feel like the code should be refactored.
 */
public function unblockUser(Some_User_Class $user, $unblockUserId) {
}

---

恐怕，
@return-array
是最好的选择，除非数组是同质的，在这种情况下，
@return-array
可能更适用。“@return-array”是“正确”选项，因为“正确”是在返回复杂数组变得更常见之前定义的。“@return mixed[]”已演变为一种表示“一个数组，其值的数据类型不同”的方法。一些IDE已经逐渐认识到这种用法。当值都是同一类型时，例如一个类Foo，它可以是“@return Foo[]”。我一直认为这个用例是一种代码味道，促使我考虑应该定义一个新类。我最终返回了那个新类，“@return MyNewClass”。