PHPDoc para matrizes de comprimento variável de argumentos

Question

Existe uma sintaxe para documentar funções que tomam uma única matriz de configuração, ao invés de parâmetros individuais?

Estou pensando especificamente bibliotecas CodeIgniter de estilo, que usam um mecanismo semelhante a este:

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

?>

Então, minha pergunta é, existe alguma maneira supprted de documentar a matriz de configuração além de apenas a descrição puramente textual? Na verdade especificando um @param [type] [name] [desc] adequada que permite PHPDoc para analisar a valores úteis?

Como um aparte, CodeIgniter realmente apenas substituí-lo próprios valores com aqueles passados ??na via do array $ config como acima, efetivamente permitindo-lhe espancar membros privados. Eu não sou um fã, mas eu estou preso com ele.

Answer 1

Eu nunca vi qualquer "boa" maneira de documentar isso - e eu nunca vi nada que pudesse ser usado por IDEs (tais como Eclipse PDT) para parâmetros insinuando ou: - (

eu teria dito " fazer como o seu quadro faz ", mas como você disse, o que ele faz, aqui, não é bom o suficiente ...

Talvez uma lista rápida / tipo de chaves possíveis pode ser melhor do que nada, embora; um pouco como este:

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

Não tenho certeza como ele seria interpretado por phpDocumentor ou um IDE ... Mas pode valer a pena tentar?

Esta é, aliás, uma das razões por que eu tendem a evitar esse tipo de forma de passagem de parâmetros -. Pelo menos quando não há também muitos (opcional) parâmetros para um método

Answer 2

A notação @ param matriz correcta para matrizes é como especificado na PHPlint

Você pode usá-lo para documentar uma matriz de configuração de uma forma útil:

Exemplo:

 /**
 * 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');
}

Answer 3

Você pode fazer isso:

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

e netbeans vai buscá-lo, mas messes PHPDoc a documentação

Answer 4

Eu sempre usar tags <pre> em situações como esta. Ex:.

/**
 * @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>
 */

A maioria das IDEs e geradores de documentação que tenho usado parecem tornar isso de uma maneira razoável, embora, claro, eles não fornecem qualquer tipo de verificação ou inspeção dos parâmetros de matriz.

Answer 5

Atualmente, não há "oficial" (como em 'suportado por várias ferramentas') maneira de fazer isso.

O PHP FIG está discutindo isso no momento em https: // groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

Answer 6

A descrição de texto, em qualquer grau de perfeição que você quer, é realmente sua única opção. Você pode torná-lo tão legível quanto quiser, mas as ferramentas de análise de código (phpDocumentor, suporte IDE) têm nenhuma maneira de saber como o seu $array é realmente estruturado em tempo de execução.

Eu concordo com os muitos comentadores que escrever código desta forma o intercâmbio de codificação conveniência para a legibilidade do código.

Answer 7

Eu usei classes.

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

Ele funciona razoavelmente bem, o principal problema é que o código torna-se repleta de classes específicas. Eles podem ser aninhados de modo peças de configuração podem ser reutilizados.