php - 为参数更改的函数编写注释 block

Question

根据 $data 参数类型行为略有不同，如何最好地为此函数编写注释。

/**
 * Appends data
 *
 * @param mixed - data array
 * @param value
 * @return self
 */
public function addData($data, $value = '')
{
    if(is_array($data)){
        $this->data = array_merge($this->data, $data);
    } else {
        if($value != ''){
            $this->data[$data] = $value;
        } else {
            $this->data[] = $data;
        }
    }
    return $this;
}

例子:

$this->addData($my_array);
$this->addData('my_var', $my_var);
$this->addData($my_var);

更新:

/**
 * Appends data
 *
 * @param array|string - This can be either an array to be merged
 *                       OR a value to be added to than array
 *                       OR a key if the $value param is set.
 * @param string - If set the first $data parma will be used as the key.
 * @return object
 */

Answer 1

@param后面应该是你传递的变量的类型，如果有几种可能的类型，你可以用|隔开，像这样:

 /**
 * Appends data
 *
 * @param array|string
 * @param string
 * @return object
 */

有更详细的例子，有类型、变量名和描述:

 /**
 * Appends data
 *
 * @param array|string $parameterOne This is used for...
 * @param string $parameterTwo Optional because...
 * @return object
 */

这是来自 PHPDoc 网站 (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html) 的语法:

@param datatype1|datatype2 $paramname description