PHPDoc用于可变长度数组参数 [英] PHPDoc for variable-length arrays of arguments

问题描述

有文档的函数的语法需要一个配置数组，而不是单个参数？

Is there a syntax for documenting functions which take a single configuration array, rather than individual parameters?

我想具体的CodeIgniter风格的库，类似的机制：

I'm thinking specifically of CodeIgniter-style libraries, which use a mechanism similar to this:

<?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解析出有用的值？

So my question is, is there some supprted way of documenting the configuration array beyond just the purely textual description? Actually specifying a proper @param [type] [name] [desc] that allows PHPDoc to parse out useful values?

另外，CodeIgniter真的只是覆盖它自己的值，通过$ config数组中传入的上面，有效地允许你破坏私人成员。

As an aside, CodeIgniter really does just overwrite it's own values with those passed in via the $config array as above, effectively allowing you to clobber private members. I'm not a fan, but I'm stuck with it.

推荐答案

我从来没有见过任何好的方式记录这个 - 我从来没有看到任何可以由IDEs（如Eclipse PDT）使用的参数hinting的参数： - （

I've never seen any "good" way of documenting this -- and I've never seen anything that could be used by IDEs (such as Eclipse PDT) for parameters hinting either :-(

我会说做你的框架，但正如你所说的，它在这里做的不够好...

I would have said "do like your framework does", but as you said, what it does, here, is not quite good enough...

也许快捷/排序可能的键列表可能比没有更好，有点像这样：

Maybe a quick/sort list of possible keys might be better than nothing, though ; a bit like this :

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

b $ b

不知道如何解释phpDocumentor或IDE ...但是可能值得一试吗？

Not sure how it would be interpreted by phpDocumentor or an IDE... But might be worth a try ?

这是，btw ，一个原因是为什么我倾向于避免这种传递参数的方式 - 至少当一个方法没有太多（可选）参数。

这篇关于PHPDoc用于可变长度数组参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！