¿Existe alguna manera de que phpDoc documente una matriz de objetos como un parámetro?

En phpDoc-documentación generada puedo causar phpDoc para generar un enlace a una definición de tipo personalizado para un parámetro determinado, utilizando¿Existe alguna manera de que phpDoc documente una matriz de objetos como un parámetro?

@param CustomType $variablename

y que funciona muy bien. Sin embargo, el código que actualmente estoy documentando requiere parámetros CustomType [], es decir, una matriz de dicho CustomType. Quiero que la documentación es evidente que se requiere una matriz, pero cuando se utiliza

@param CustomType[] $variablename

phpDoc ya no reconoce el tipo, y por lo tanto no se puede enlazar a su definición. Esto es bastante importante en este caso: estoy documentando una API que tiene algunos tipos bastante complejos que deben proporcionarse.

He intentado varias sintaxis diferentes para esto y todas tratan las entradas como tipos de variables independientes o como reconocimiento de tipo de salto en la documentación.

Salvo esto, solo lo anotaré en la nota del parámetro, pero parece más claro mostrar la matriz del parámetro en el tipo.

EDITAR

Con phpDocumentor 2 (que se fusionó con DocBlox) las obras de sintaxis

@param CustomType[] $paramName

, y como se señaló en la respuesta de @ PhpStorm Styx es compatible con el tipo-dando a entender que con la sintaxis.

Respuesta aceptada actualizada adecuadamente.

Fuente

2012-02-03 cori

Posible duplicado: http://stackoverflow.com/questions/778564/phpdoc-type-hinting-for-array-of-objects –

no realmente; son complementarios; pregunta por las insinuaciones de tipo en el IDE, mientras que el mío era sobre la documentación de phpDoc en sí misma; la sugerencia de tpe es solo un buen efecto secundario en mi caso. – cori

Para documentar la forma de una matriz asociativa, consulte https://stackoverflow.com/questions/14612773/php-docblocks-explaining-an-array?noredirect=1&lq=1; un enfoque es https: // github. com/phpDocumentor/fig-standards/issues/30 # issue-20061866 –

Nueva versión de PHP doc support /** @var sometype[] */ sintaxis. Aún más complicado: /** @var (sometype|othertype)[] */. http://www.phpdoc.org/docs/latest/guides/types.html#arrays PHPStorm también admite esta sintaxis.

Fuente

2012-09-05 10:41:48 Styx

sheesh te amo – user544262772

Lo mejor que puede hacer es:

@param array $variablename an array of {@link CustomType} objects

Esto debería ayudar al lector a comprender el verdadero tipo de datos de $ nombredevariable, si bien indican la expectativa de lo que contiene la matriz.

Esto no será suficiente para ayudar a la autocompletación de un IDE cuando se trata de usar un miembro de $ nombreVariable y esperar que las propiedades/métodos de CustomType aparezcan. Realmente no hay forma de obtener ese comportamiento actualmente.

Fuente

2012-02-03 19:43:05 ashnazg

Concedido, hay un esfuerzo en curso para tener una sintaxis de firma de tipo de datos de "CustomObject []" => "una matriz de miembros CustomObject". Una vez que esté disponible en un generador de documentación, espero que los IDEs sigan probablemente para respaldar su significado. – ashnazg

http://docs.docblox-project.org/for-users/types.html#arrays – ashnazg

eso es más o menos a lo que me he resignado, pero el enlace a docblox podría valer la pena. ¡Gracias! – cori

Vea los ejemplos siguientes de: https://code.google.com/p/google-api-php-client/source/checkout donde se describe la estructura de matriz de los parámetros de entrada.

/** 
    * Set the OAuth 2.0 access token using the string that resulted from calling authenticate() 
    * or Google_Client#getAccessToken(). 
    * @param string $accessToken JSON encoded string containing in the following format: 
    * {"access_token":"TOKEN", "refresh_token":"TOKEN", "token_type":"Bearer", 
    * "expires_in":3600, "id_token":"TOKEN", "created":1320790426} 
    */ 


/** 
    * Insert a new file. (files.insert) 
    * 
    * @param Google_DriveFile $postBody 
    * @param array $optParams Optional parameters. 
    * 
    * @opt_param bool convert Whether to convert this file to the corresponding Google Docs format. 
    * @opt_param string targetLanguage Target language to translate the file to. If no sourceLanguage is provided, the API will attempt to detect the language. 
    * @opt_param string sourceLanguage The language of the original file to be translated. 
    * @opt_param string ocrLanguage If ocr is true, hints at the language to use. Valid values are ISO 639-1 codes. 
    * @opt_param bool pinned Whether to pin the head revision of the uploaded file. 
    * @opt_param bool ocr Whether to attempt OCR on .jpg, .png, or .gif uploads. 
    * @opt_param string timedTextTrackName The timed text track name. 
    * @opt_param string timedTextLanguage The language of the timed text. 
    * @return Google_DriveFile 
    */

Fuente

2012-10-02 10:28:58

No se menciona que @opt_param sea compatible con el sitio web/referencia de phpdoc http://phpdoc.org/docs/latest/references/phpdoc/index.html o en la documentación propuesta de PSR5 en https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md: quienquiera que haya creado el docblock que ha copiado también puede haber escrito @ this_wont_work_param (!) – kguest

Documentar las claves de una matriz está en discusión en https://github.com/phpDocumentor/phpDocumentor2/issues/650 –

La documentación phpdoc observa en http://www.phpdoc.org/docs/latest/guides/types.html

array

una colección de variables de tipo desconocido. Es posible especificar los tipos de miembros de la matriz, consulte el capítulo sobre matrices para obtener más información.

Y ... no hay ningún enlace ni capítulo "en matrices". Así que no, esto parece una característica próxima.

Fuente

2014-11-11 04:33:52

¿Existe alguna manera de que phpDoc documente una matriz de objetos como un parámetro?

Respuesta

Cuestiones relacionadas