用於可變長度參數數組的PHPDoc

是否存在用於記錄採用單個配置數組而不是單個參數的函數的語法？用於可變長度參數數組的PHPDoc

我特別想笨樣式庫，它使用類似這樣的機制：

<?php 

// 
// Library definition 
// 

class MyLibrary { 
    var $foo; 
    var $bar; 
    var $baz; 
    // ... and many more vars... 


    /* Following is how CodeIgniter documents their built-in libraries, 
    * which is mostly useless. AFAIK they should be specifying a name 
    * and description for their @param (which they don't) and omitting 
    * @return for constructors 
    */ 

    /** 
    * @access public 
    * @param array 
    * @return void 
    */ 
    function MyLibrary($config = array()) { 
    foreach ($config as $key => $value) { 
     $this->$key = $value; 
    } 
    } 
} 

// 
// Library usage: 
// 

// Iniitialize our configuration parameters 
$config['foo'] = 'test'; 
$config['bar'] = 4; 
$config['baz'] = array('x', 'y', 'z'); 

$x = new MyLibrary($config); 

?>

所以我的問題是，是否有記錄配置陣列不僅僅是純文本的一些supprted方式描述？其實指定一個合適的@param [type] [name] [desc]允許PHPDoc解析出有用的值？另外，CodeIgniter實際上只是用上面通過$ config數組傳入的值覆蓋它自己的值，從而有效地允許您打開私有成員。我不是粉絲，但我堅持不懈。

來源

2010-01-05 meagar

我從來沒有見過這種記錄任何「好」的方式 - 我從來沒有見過任何可以通過IDE的（比如Eclipse PDT）使用的提示參數無論是:-(

我會說「不喜歡你的框架做」，但正如你所說，它做什麼，在這裏，是不是很夠好......

也許可能密鑰的快速/排序列表可能總比沒有好，但是;有點像這樣：

@param array $config [key1=>int, otherKey=>string]

不知道它將如何解釋phpDocumentor或IDE ...但可能值得一試？

這是，順便說一句，爲什麼我傾向於避免這種傳遞參數的方式 - 至少當方法沒有太多（可選）參數時。

來源

2010-01-05 21:12:46

如果可以的話，我會避免它，不幸的是，CodeIgniter的慣例要求使用這種粗糙的配置數組，而不是使用常規的舊參數。 – meagar 2010-01-05 21:17:38

@meagar：是的，我猜/理解，但無法抗拒^^（如果其他人有一天會到達這個問題/答案，這可能會有所幫助） – 2010-01-05 21:18:36

這與我的做法相似。 PHPDoc將採用該列表並將其添加到文檔中，就像任何其他字符串一樣，所以它比沒有任何更好。雖然PDT無法理解它。它只會知道它是一個數組。 – Gordon 2010-01-05 21:21:30

無論你想要什麼程度的完整性，文字描述都是你唯一的選擇。您可以根據需要使其清晰易讀，但代碼分析工具（phpDocumentor，IDE支持）無法知道您的$array在運行時是如何實際構建的。

我同意許多評論者這樣寫代碼交換編碼方便代碼易讀性。

來源

2010-01-06 21:00:28 ashnazg

數組正確陣列@參數表示法是如PHPlint

指定可以使用它來記錄以有用的方式一個配置數組：

實施例：

/** 
* Does stuff 
* 
* @param array[int|string]array[string]Object $config 
* 
* @return array[int]string 
*/ 
public function foo(array $config) 
{ 
    // do stuff here 

    return array('foo', 'bar', 'baz'); 
}

來源

2010-10-21 13:47:57 Structed

這並沒有解決我關於記錄哪些特定數組鍵用作可選命名參數的問題。 – meagar 2010-10-21 13:52:09

是的，不是直接的。但我想指出lint符號，它可以幫助您以有用的方式記錄這樣的配置數組。我相應地編輯了我的答案。 – Structed 2013-05-24 09:18:56

你可以這樣做：

 
/** 
* @param array $param1 
* @param string $param1['hello'] 
*/ 
function hey($param1) 
{ 
}

和netbeans會將它撿起來，但phpdoc弄亂了文檔

來源

2011-08-29 22:34:50

帶有PHP插件1.17.1的Netbeans 7.0.1不解釋Eclipse 3.7.2和PDT 3.1.1 – cweiske 2012-10-04 08:11:50

我總是在這種情況下使用<pre>標籤。防爆。：

/** 
* @param array $ops An array of options with the following keys:<pre> 
*  foo: (string) Some description... 
*  bar: (array) An array of bar data, with the following keys: 
*   boo: (string) ... 
*   far: (int) ... 
*  baz: (bool) ... 
* </pre> 
*/

大多數IDE和文檔生成器我用似乎使這個以合理的方式，但他們當然不提供參數數組中的任何類型檢查或檢查。

來源

2012-06-01 19:19:48

目前沒有「官方」（如在'多種工具支持'）的方式來做到這一點。

的PHP圖此刻討論它在https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

來源

2012-10-04 08:14:14 cweiske

我使用的類。

<?php 
class MyLibrary { 
    var $foo; 
    var $bar; 
    var $baz; 

    /** 
    * @param MyLibraryConfig|null $config 
    */ 
    function MyLibrary($config = null) { 
     if (isset($config->foo)) { 
      $this->foo = $config->foo; 
     } 
     if (isset($config->baz)) { 
      $this->baz = $config->baz; 
     } 
     if (isset($config->bar)) { 
      $this->bar = $config->bar; 
     } 
    } 
} 

/** 
* @property string $foo 
* @property int $bar 
* @property array $baz 
*/ 
class MyLibraryConfig { 
}

它工作得很好，主要問題是代碼變得亂七八糟的特定類。它們可以嵌套，因此可以重用部分配置。

來源

2012-10-15 09:52:32 Odalrick

用於可變長度參數數組的PHPDoc

回答

相關問題