用于可变长度参数数组的 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.

推荐答案

我从来没有见过任何好的"方式来记录这个——我从来没有见过任何可以被 IDE 使用的东西(例如作为 Eclipse PDT) 用于参数提示 :-(

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]

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

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

顺便说一句，这是我倾向于避免这种传递参数的方式的一个原因——至少在一个方法没有太多(可选)参数时.

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