11

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

我正在特别考虑 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 数组传入的值覆盖了它自己的值，从而有效地允许您破坏私有成员。我不是粉丝，但我坚持下去。

4

7 回答 7

11

我从来没有见过任何“好的”记录方式——而且我从来没有见过任何可以被 IDE （例如 Eclipse PDT）用于参数提示的东西:-(

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


不过，可能的键的快速/排序列表可能总比没有好；有点像这样：

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

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

顺便说一句，这就是为什么我倾向于避免这种传递参数的方式的一个原因——至少在一个方法没有太多（可选）参数的情况下。

于 2010-01-05T21:12:46.530 回答
4

数组的正确数组 @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');
}
于 2010-10-21T13:47:57.150 回答
2

你可以这样做：

/**
 * @param 数组 $param1
 * @param 字符串 $param1['hello']
 */
功能嘿（$param1）
{
}

和 netbeans 会拿起它，但 phpdoc 弄乱了文档

于 2011-08-29T22:34:50.583 回答
1

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

于 2012-06-01T19:19:48.240 回答
1

目前没有“官方”（如“由多种工具支持”）方式来做到这一点。

PHP FIG 目前正在https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion讨论它

于 2012-10-04T08:14:14.740 回答
0

文本描述，无论你想要什么程度的完整性，都是你唯一的选择。您可以根据需要使其清晰易读，但代码分析工具（phpDocumentor、IDE 支持）无法知道您$array在运行时的实际结构。

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

于 2010-01-06T21:00:28.297 回答
0

我用过类。

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

它工作得很好，主要问题是代码中到处都是特定的类。它们可以嵌套，因此可以重复使用部分配置。

于 2012-10-15T09:52:32.920 回答