用于可变长度参数数组的 PHPDoc
Posted
技术标签:
【中文标题】用于可变长度参数数组的 PHPDoc【英文标题】:PHPDoc for variable-length arrays of arguments 【发布时间】:2011-01-01 19:42:10 【问题描述】:是否有用于记录采用单个配置数组而不是单个参数的函数的语法?
我特别想到了 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 数组传入的值覆盖了它自己的值,从而有效地允许您破坏私有成员。我不是粉丝,但我坚持下去。
【问题讨论】:
【参考方案1】:数组的正确数组@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');
【讨论】:
这并没有解决我关于记录哪些特定数组键用作可选命名参数的问题。 是的,不是直接的。但我想指出 lint 表示法,它可以帮助您以有用的方式记录这样的配置数组。我相应地编辑了我的答案。【参考方案2】:我用过类。
<?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
它工作得很好,主要问题是代码中到处都是特定的类。它们可以嵌套,因此可以重复使用部分配置。
【讨论】:
【参考方案3】:目前没有“官方”(如“受多种工具支持”)方式来执行此操作。
PHP FIG 正在https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion 讨论它
【讨论】:
【参考方案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 和文档生成器似乎都以合理的方式呈现它,尽管它们当然不提供任何类型检查或数组参数检查。
【讨论】:
【参考方案5】:我从未见过任何“好”的记录方式——而且我从未见过 IDE 可以使用任何东西(例如 Eclipse PDT) 来提示参数:- (
我会说“像你的框架那样做”,但正如你所说,它在这里所做的还不够好......
不过,可能的键的快速/排序列表可能总比没有好;有点像这样:
@param array $config [key1=>int, otherKey=>string]
不确定 phpDocumentor 或 IDE 将如何解释它...但可能值得一试?
顺便说一句,这就是为什么我倾向于避免这种传递参数的方式的一个原因——至少在一个方法没有太多(可选)参数的情况下。
【讨论】:
如果可以的话,我会避免它,不幸的是 CodeIgniter 的约定需要这种草率的配置数组使用,而不是,哦,说,常规的旧参数。 @meagar :是的,我猜到/理解了,但无法抗拒 ^^(如果有一天其他人提出这个问题/答案,这可能会有所帮助) 这与我的做法类似。 PHPDoc 将获取列表并将其添加到文档中,就像任何其他字符串一样,所以总比没有好。 PDT 无法理解它。它只会知道它是一个数组。【参考方案6】:你可以这样做:
/** * @param 数组 $param1 * @param 字符串 $param1['hello'] */ 功能嘿($param1)netbeans 会接收它,但 phpdoc 会弄乱文档
【讨论】:
带有 PHP 插件 1.17.1 的 Netbeans 7.0.1 不能解释这一点,带有 PDT 3.1.1 的 Eclipse 3.7.2 也不能解释【参考方案7】:文字描述,无论你想要什么程度的完整性,都是你唯一的选择。您可以根据需要使其清晰易读,但代码分析工具(phpDocumentor、IDE 支持)无法知道您的 $array
在运行时的实际结构。
我同意许多以这种方式编写代码的评论者的观点,即以编码方便换取代码易读性。
【讨论】:
以上是关于用于可变长度参数数组的 PHPDoc的主要内容,如果未能解决你的问题,请参考以下文章
将 alloca() 用于可变长度数组是不是比在堆上使用向量更好?