php - 複雑な戻り値の PHPDoc コメントをフォーマットする方法

Question

次の構造のようなものを返す関数があります。

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

関数のコメントでこの戻り値を正しくフォーマットする方法は?

私の推測は次のとおりです。

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

助言がありますか？

Answer 1

奇妙な配列を返す必要がある場合は、それを単純で理解しやすいものとして文書化します。

これが私がそれをする方法です。@return array代わりに自由に使用して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) {
}

Answer 2

少しやり過ぎかもしれませんが、通常の配列ではなく、特定のインターフェイスを持つオブジェクトを返すことができます。何かのようなもの：

/**
 * @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;
    }
}