如何在phpDoc/javaDoc中記錄訪問器/增變器方法？

Question

鑑於其表現爲無論是根據傳遞給它的參數賦值函數或訪問，這樣的功能：

// in PHP, you can pass any number of arguments to a function... 
function cache($cacheName) { 
    $arguments = func_get_args(); 

    if (count($arguments) >= 2) { // two arguments passed. MUTATOR. 

     $value = $arguments[1];    // use the second as the value 
     $this->cache[$cacheName] = $value; // *change* the stored value 

    } else { // 1 argument passed, ACCESSOR 
     return $this->cache[$cacheName]; // *get* the stored value 
    } 
} 

cache('foo', 'bar'); // nothing returned 
cache('foo')   // 'bar' returned 

如何在PHPDoc的或類似的自動記錄創造者記錄呢？我原本只是寫這樣的：

/** 
* Blah blah blah, you can use this as both a mutator and an accessor: 
* As an accessor: 
* @param $cacheName name of the variable to GET 
* @return string  the value... 
* 
* As a mutator: 
* @param $cacheName name of the variable to SET 
* @param $value  the value to set 
* @return void 
*/ 

然而，當這是通過PHPDoc的運行，它抱怨，因爲有2個標記，並且第一@param $cacheName描述由第二覆蓋。

有沒有辦法解決這個問題？

Answer 1

正如您發現的那樣，您無法記錄單個函數的2個不同簽名。但是你可以做什麼， - 如果你使用phpDocumentor - ，是記錄optional function parameters和multiple possible return types：

/** 
* Blah blah blah, you can use this as both an accessor and a mutator, e.g. 
* <code>cache('name') // get cache value</code> 
* and 
* <code>cache('name', 'value') // set new cache value</code>. 
* 
* @param string $cacheName name of the variable to GET|SET 
* @param string $value  optional new value 
* 
* @return string|void value of $cacheName or, in case of mutator, void 
*/ 

爲清楚起見，我也將包括使用示例。