PHPDoc para matrices de argumentos de longitud variable

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

Estoy pensando específicamente en las bibliotecas de estilo CodeIgniter, que usan un mecanismo similar a este:

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

Entonces, mi pregunta es, ¿hay alguna manera de documentar el conjunto de configuración más allá de la descripción puramente textual? ¿En realidad especificando un @param [type] [name] [desc] adecuado que permita a PHPDoc analizar los valores útiles?

Como comentario adicional, CodeIgniter realmente sobrescribe sus propios valores con los ingresados ​​a través de la matriz $ config como se indica arriba, lo que le permite interceptar miembros privados. No soy fan, pero estoy atrapado en eso.

Nunca he visto una forma “buena” de documentar esto, y nunca he visto nada que los IDE (como Eclipse PDT) puedan usar para parámetros que sugieran 🙁

Hubiera dicho ” haz como tu framework “, pero como dijiste, lo que hace, aquí, no es lo suficientemente bueno …

Sin embargo, tal vez una lista rápida / ordenada de claves posibles sea mejor que nada; un poco como esto:

 @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.

La notación correcta de array @param para arrays es la especificada en PHPlint

Puede usarlo para documentar una matriz de configuración 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'); } 

Puedes hacerlo:

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

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

Siempre uso tags


en situaciones como esta. Ex.:

 /** * @param array $ops An array of options with the following keys:
 * foo: (string) Some description... * bar: (array) An array of bar data, with the following keys: * boo: (string) ... * far: (int) ... * baz: (bool) ... * 

*/

La mayoría de los IDEs y los generadores de documentación que he utilizado parecen representar esto de una manera razonable, aunque, por supuesto, no proporcionan ningún tipo de verificación o inspección de los parámetros de la matriz.

Actualmente no existe una forma “oficial” (como en “compatible con múltiples herramientas”) para hacer esto.

El PHP FIG lo está discutiendo en este momento en https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion

Una descripción de texto, en cualquier grado de compleción 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 $array está realmente estructurado en tiempo de ejecución.

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

He usado clases.

 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.