参数可变长度数组的PHPDoc

对于采用单个配置数组而不是单个参数的函数，是否有一种用于记录的语法

我特别想到了CodeIgniter风格的库，它使用类似于以下的机制：

<?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);

?>

我从来没有见过任何“好”的方法来记录这一点——我也从来没有见过IDE（比如Eclipse PDT）可以使用任何方法来表示以下内容的参数：-(

我会说“像你的框架那样做”，但正如你所说，它在这里所做的还不够好



也许一个可能的键的快速/排序列表可能比什么都没有要好；有点像这样：

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

不确定phpDocumentor或IDE将如何解释它…但可能值得一试

顺便说一句，这就是为什么我倾向于避免这种传递参数的方式的一个原因——至少在一个方法没有太多（可选）参数的情况下是如此。
文本描述，无论你想要达到什么程度，实际上是你唯一的选择。你可以让它尽可能清晰，但代码分析工具除外（phpDocumentor，IDE支持）无法知道
$array
在运行时的实际结构

我同意许多评论者的观点，即以这种方式编写代码可以换取代码易读性的编码便利。
正确的数组@param表示法如中所述

您可以使用它以一种有用的方式记录配置数组：

示例：

 /**
 * 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');
}

您可以这样做：

/**
 * @param array $param1
 * @param string $param1['hello']
 */
function hey($param1)
{
}
/**
*@param数组$param1
*@param字符串$param1['hello']
*/
函数（参数1）
{
}
netbeans会把它捡起来，但phpdoc会把文档弄乱
在这种情况下，我总是使用
标记。例如：

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

<?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 {
}

/**
*@param array$ops具有以下键的选项数组：
*傅：（字符串）一些描述。。。
*bar：（数组）具有以下键的条形数据数组：
*boo：（字符串）。。。
*远：（int）。。。
*巴兹：（嘘）。。。
* 
*/

我使用过的大多数IDE和文档生成器似乎都以合理的方式呈现了这一点，尽管它们当然不提供对数组参数的任何类型检查或检查。
目前没有“官方”（如“由多个工具支持”）方法来实现这一点

PHP FIG目前正在讨论它，我使用了类

如果可以的话，我会避免它，不幸的是，CodeIgniter的约定要求这种草率的配置数组使用，而不是，哦，比如说，常规的旧参数。@meagar：是的，我猜/理解，但无法抗拒^^^（如果有一天有人提出这个问题/答案，这可能会有所帮助）这与我的做法类似。PHPDoc将获取列表并将其添加到文档中，就像任何其他字符串一样，因此它总比没有好。但PDT无法理解它。它只知道它是一个数组。这并没有解决我关于记录哪些特定数组键用作可选命名参数的问题。是的，不是直接的但是我想指出lint符号，它将帮助您以一种有用的方式记录这样的配置数组。我相应地编辑了我的答案。带有PHP插件1.17.1的Netbeans 7.0.1不能解释这一点，带有PDT 3.1.1的Eclipse 3.7.2也不能解释这一点