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

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

10 голосов
/ 06 января 2010

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

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

Ответы [ 7 ]

10 голосов
/ 06 января 2010

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

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


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

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

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

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

4 голосов
/ 21 октября 2010

Правильная запись массива @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');
}
2 голосов
/ 30 августа 2011

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

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

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

1 голос
/ 04 октября 2012

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

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

1 голос
/ 01 июня 2012

Я всегда использую <pre> теги в подобных ситуациях.Пример: 

<code>/**
 * @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) ...
 *
* /

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

0 голосов
/ 15 октября 2012

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

<?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 голосов
/ 07 января 2010

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

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

...