代码之家 › 专栏 › 技术社区 › user229044

变长参数数组的phpDoc

phpdoc comments codeigniter php

user229044 · 技术社区 · 15 年前

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

我特别考虑的是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解析有用的值?

顺便提一句,codeigner确实只是用上面通过$config数组传入的值覆盖它自己的值,有效地允许您击溃私有成员。我不是一个粉丝,但我一直坚持着。

7 回复 | 直到 11 年前

Pascal MARTIN 13 年前

我从未见过任何“好”的方式来记录这一点——我也从未见过任何可以被IDES使用的东西。 (如Eclipse PDT) 参数提示:-(

我本来会说 像你的框架一样 “,但正如你所说的,它在这里做的还不够好……

不过,也许一个可能的快捷/排序键列表可能比什么都没有要好;有点像这样:

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

不确定phpdocumentor或ide如何解释它…但也许值得一试?

顺便说一句,这就是为什么我倾向于避免这种传递参数的方式的一个原因——至少当一个方法没有太多(可选)参数时。

Structed 12 年前

数组的正确array@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');
}

Moazzam Khan 13 年前

您可以这样做:

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

Netbeans会把它捡起来,但是phpdoc把文件弄乱了

Jason Grimes 13 年前

我总是使用 <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>
 */

我使用的大多数IDES和文档生成器似乎以合理的方式呈现这一点,尽管它们当然不提供任何类型检查或数组参数检查。

cweiske agentofuser 12 年前

目前没有“官方”(如“多个工具支持”)的方法来实现这一点。

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

user229044 14 年前

文本描述,无论您想要什么程度的完整性,都是您唯一的选择。您可以根据需要使其易读,但代码分析工具(phpdocumentor、ide支持)无法知道 $array 实际上是在运行时构建的。

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

Odalrick 12 年前

我上过课。

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

它工作得相当好,主要问题是代码中有很多特定的类。它们可以嵌套,这样配置的某些部分就可以重用。