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);

?>

Таким образом, мой вопрос, там некоторый supprted способ зарегистрировать массив конфигурации вне просто чисто текстового описания? На самом деле определение надлежащего @param [type] [name] [desc] это позволяет PHPDoc анализировать полезные значения?

Как в стороне, CodeIgniter действительно просто перезаписывает свои собственные значения с переданными на пути массив $config как выше, эффективно позволяя Вам ударить членов парламента, не занимающих официального поста. Я не поклонник, но я застреваю с ним.

11
задан meagar 27 January 2014 в 21:29
поделиться

2 ответа

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

Я бы сказал "do like your framework does", но как вы сказали, то, что он делает, здесь не достаточно хорошо....


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

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

Не знаю, как это будет интерпретироваться phpDocumentor или IDE.... Но стоит попробовать ?

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

11
ответ дан 3 December 2019 в 06:21
поделиться

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

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

0
ответ дан 3 December 2019 в 06:21
поделиться
Другие вопросы по тегам:

Похожие вопросы: