PHPDoc 变长参数数组

Question

有没有一种语法来记录接受单个配置数组而不是单独参数的函数？

我特别考虑 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);

?>

所以我的问题是，有没有一种支持的方式来记录配置数组，除了纯文本描述之外？实际上，指定一个适当的@param [type] [name] [desc]可以让PHPDoc解析出有用的值吗？

另外，CodeIgniter确实只是使用上面通过$config数组传递的值来覆盖自己的值，有效地允许您破坏私有成员。我不是粉丝，但我被困住了。

- user229044

Answer 1

我从未看过任何“好”的文档方式，也从未见过可以用于IDE提示（例如Eclipse PDT）的东西，对此感到非常遗憾:(

我本来想说“像你的框架一样做”，但正如你所说，它所做的在这里并不太够......

也许列出可能键的快速/排序列表总比没有更好；就像这样：

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

不确定它是否会被phpDocumentor或IDE解释...但值得一试吗？

顺便说一下，这也是我倾向于避免使用这种参数传递方式的原因之一--至少在方法中没有太多（可选）参数的情况下。

- Pascal MARTIN

---

如果可以的话，我会避免这种做法。不幸的是，CodeIgniter 的约定要求使用这种松散的配置数组，而不是常规的旧参数。 - user229044

@meagar：是的，我猜到/明白了，但还是忍不住要发表一下 ^^ （如果有人在未来某一天遇到这个问题，这可能会对他们有所帮助） - Pascal MARTIN

这跟我做的方式很相似。PHPDoc会将该列表添加到文档中，就像其他字符串一样，所以总比没有好。但是PDT无法理解它，它只知道它是一个数组。 - Gordon

Answer 2

数组的正确@param符号表示法是按照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');
}

- Structed

---

这并没有回答我的问题，即如何记录使用作为可选命名参数的特定数组键。 - user229044

是的，不是直接的方法。但我想指出lint注释，这将有助于您以有用的方式记录此类配置数组。我相应地编辑了我的答案。 - Structed

Answer 3

您可以这样做：

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

NetBeans将会识别它，但是phpdoc会弄乱文档。

- Moazzam Khan

---

Netbeans 7.0.1带有PHP插件1.17.1无法解释它，Eclipse 3.7.2带有PDT 3.1.1也无法解释。 - cweiske

Answer 4

我在这种情况下总是使用<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和文档生成器似乎以合理的方式呈现了这个，尽管它们当然不提供任何类型检查或数组参数的检查。

- Jason Grimes

Answer 5

目前还没有一种“官方”的方法（即由多个工具支持）来实现这一点。

PHP FIG正在https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion讨论此问题。

- cweiske

Answer 6

我已经使用了类。

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

它的工作相当不错，主要问题是代码变得充斥着特定的类。它们可以嵌套，因此配置的部分可以被重用。

- Odalrick

Answer 7

一个文本描述，无论你想要多完整，都是你唯一的选择。你可以让它尽可能易读，但代码分析工具（phpDocumentor、IDE支持）无法知道你的$array在运行时实际上是如何结构化的。

我同意许多评论者的观点，以这种方式编写代码会将编码方便性换成代码易读性。

- ashnazg