PHPDoc для массивов аргументов переменной длины

Существует ли синтаксис для документирования функций, которые принимают один массив конфигурации, а не отдельные параметры?

Я имею в виду, в частности, библиотеки в стиле 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, как указано выше, эффективно позволяя вам блокировать частных участников. Я не фанат, но я застрял с этим.

Author: meagar, 2010-01-06
Source

7 answers

Я никогда не видел никакого "хорошего" способа документирования этого - и я никогда не видел ничего, что могло бы использоваться IDE (например, Eclipse PDT) для параметров, намекающих либо:-(

Я бы сказал " делайте так, как делает ваш фреймворк", но, как вы сказали, то, что он делает здесь, недостаточно хорошо...


Возможно, быстрый/сортировочный список возможных ключей может быть лучше, чем ничего; немного похоже на это:

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

Не уверен, как это будет истолковано phpDocumentor или IDE... Но, может быть, стоит попробовать?

Это, кстати, одна из причин, по которой я стараюсь избегать такого способа передачи параметров - по крайней мере, когда в методе не слишком много (необязательных) параметров.

 10
Author: Pascal MARTIN, 2011-11-14 16:32:57

Правильная нотация 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');
}
 4
Author: Structed, 2013-05-24 09:18:31

Вы можете сделать это: 

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

И netbeans подхватит его, но phpdoc испортит документацию

 2
Author: Moazzam Khan, 2011-08-29 22:34:50

Я всегда использую теги <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 и генераторов документации, которые я использовал, похоже, отображают это разумным способом, хотя, конечно, они не обеспечивают никакой проверки типов или проверки параметров массива.

 1
Author: Jason Grimes, 2012-06-01 19:19:48

В настоящее время нет "официального" (как в "поддерживается несколькими инструментами") способа сделать это.

PHP FIG обсуждает это в данный момент по адресу https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

 1
Author: cweiske, 2012-10-04 08:14:14

Текстовое описание, с какой бы степенью полноты вы ни хотели, на самом деле является вашим единственным вариантом. Вы можете сделать его настолько разборчивым, насколько захотите, но инструменты анализа кода (phpDocumentor, поддержка IDE) не имеют возможности узнать, как на самом деле структурирован ваш $array во время выполнения.

Я согласен со многими комментаторами в том, что написание кода таким образом меняет удобство кодирования на удобочитаемость кода.

 0
Author: ashnazg, 2011-05-20 13:32:23

Я использовал классы.

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

Это работает довольно хорошо, основная проблема заключается в том, что код становится заваленным определенными классами. Они могут быть вложенными, чтобы части конфигурации можно было использовать повторно.

 0
Author: Odalrick, 2012-10-15 09:52:32