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

为参数更改的函数编写注释块

1 个答案: