PHPDoc para matrices de argumentos de longitud variable

Question

¿Existe una sintaxis para documentar funciones que toman una única matriz de configuración, en lugar de parámetros individuales?

Pienso específicamente en las bibliotecas de estilo CodeIgniter, que utilizan un mecanismo similar a esto:

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

?> 

Así que mi pregunta es, ¿hay alguna manera supprted de documentar el arreglo de configuración más allá de la puramente textual ¿descripción? ¿Especificando realmente un @param [type] [name] [desc] apropiado que permita que PHPDoc analice valores útiles?

Como un lado, CodeIgniter realmente solo sobrescribe sus propios valores con los que pasan a través de la matriz de $ config como se indica anteriormente, lo que permite derrotar a los miembros privados. No soy fan, pero estoy atrapado en eso.

Answer 1

nunca he visto ninguna manera "bueno" de documentar esto - y nunca he visto nada que pueda ser utilizado por los entornos de desarrollo (como Eclipse PDT) para los parámetros ya sea haciendo alusión :-(

habría dicho "hacer como su marco hace", pero como se ha dicho, lo que hace, aquí, no es lo suficientemente bueno ...

Tal vez una lista/ordenación rápida de claves posibles podría ser mejor que nada, sin embargo, un poco como este:

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

No estoy seguro de cómo sería interpretado por phpDocumentor o un IDE ... Pero podría valer la pena intentarlo?

Esto es, por cierto, una razón por la que tiendo a evitar ese tipo de forma de pasar parámetros, al menos cuando no hay demasiados parámetros (opcionales) para un método.

Answer 2

Una descripción de texto, con el grado de exhaustividad que desee, es realmente su única opción. Puede hacerlo tan legible como desee, pero las herramientas de análisis de código (phpDocumentor, soporte IDE) no tienen forma de saber cómo su estructura $array en realidad está estructurada en tiempo de ejecución.

Estoy de acuerdo con los muchos comentaristas que escribir código de esta manera intercambia la conveniencia de codificación para la legibilidad del código.

Answer 3

La notación @param array correcta para las matrices es el especificado en PHPlint

Se puede utilizar para documentar una matriz de config de una manera útil:

Ejemplo:

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

Puede hacer esto:

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

y netbeans lo recogerán pero phpdoc arruina la documentación

Answer 5

Siempre utilizo etiquetas <pre> en situaciones 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> 
*/ 

La mayoría de los entornos de desarrollo y generadores de documentación que he utilizado para hacer parecer esto de una manera razonable, aunque, por supuesto que no proporcionan ningún tipo de comprobación o inspección de los parámetros de matriz.

Answer 6

Actualmente no existe una manera "oficial" (como en 'compatible con múltiples herramientas') para hacer esto.

La figura PHP se está discutiendo en el momento en https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

Answer 7

He usado clases.

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

Funciona bastante bien, el principal problema es que el código se llena de clases específicas. Se pueden anidar para que partes de la configuración puedan reutilizarse.