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

【问题标题】：Writing comment block for function where parameters change为参数更改的函数编写注释块
【发布时间】：2013-07-03 15:12:41
【问题描述】：

如何最好地为此函数编写 cmets，其中基于 $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
 */

【问题讨论】：

对不起，如果有更好的地方我应该问这个
这里有一些例子pear.php.net/manual/en/standards.sample.php
不是答案，但是：对我来说，这似乎是一个可怕功能。具有相同的参数意味着不同的事情是一个坏主意，而且非常令人困惑。很难记录的事实只是其中的一个症状。如果你想做两件不同的事情（将数据合并到数组中，或者设置一个值），为什么不提供两个函数呢？

标签： php comments

【解决方案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

【讨论】：

谢谢，虽然这是我觉得最难的描述部分。我已经根据您的建议更新了问题，您能否提出任何改进建议。
您的描述很好。不过，您忘记添加 $paramname，添加它可能是个好主意。