爲參數變化的函數寫入註釋塊

如何最好地爲基於$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 
*/

來源

2013-07-03 John Magnolia

很抱歉，如果有一個更好的地方，我應該是問這個 –

這裏有一些例子http://pear.php.net/manual/en/standards.sample.php – chrislondon

不是一個答案，但：對我來說這似乎是一個*糟糕的功能。具有相同的參數意味着不同的事情是一個壞主意，而且非常混亂。事實證明這很難記錄，這只是一個症狀。如果你想做兩件不同的事情（將數據合併到數組中，或設置一個值），爲什麼不提供兩個函數？ – sleske

@參數後，它應該是你傳遞的變量的類型，如果有幾個可能的類型，你可以單獨他們用|，像這樣：

/** 
* 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

來源

2013-07-03 15:14:34

謝謝，雖然它是我發現最困難的描述部分。我已經在你的建議後更新了這個問題，你能否建議對此進行任何改進。 –

你的描述很好。您忘了添加$ paramname，但添加它可能是一個好主意。 –

爲參數變化的函數寫入註釋塊

回答

相關問題