arrays - plantilla - phpdocumentor tutorial

¿Hay una manera para que phpDoc documente una matriz de objetos como un parámetro?

Question

En la documentación generada por phpDoc puedo hacer que phpDoc genere un enlace a una definición de tipo personalizada para un parámetro dado usando

@param CustomType $variablename

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

@param CustomType[] $variablename

phpDoc ya no reconoce el tipo y, por lo tanto, no puede vincularlo 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 probado varias sintaxis diferentes para esto y todas tratan las entradas como tipos de variables independientes o reconocen el tipo de ruptura en la documentación.

De lo contrario, 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 combinó con DocBlox) el

@param CustomType[] $paramName

la sintaxis funciona, y como se indica en la respuesta de @Styx, PhpStorm admite sugerencias de tipo con esa sintaxis.

Respuesta aceptada actualizada adecuadamente.

Answer 1

Las notas de la documentación de phpdoc en http://www.phpdoc.org/docs/latest/guides/types.html

formación

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 enlace ni capítulo "sobre arreglos". Así que no, esto parece una característica próxima.

Answer 2

Lo mejor que puedes hacer es:

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

Esto debería ayudar al lector a darse cuenta del verdadero tipo de datos de $ variablename, al tiempo que indica la expectativa de lo que contiene la matriz.

Esto no será suficiente para ayudar al autocompletado de un IDE cuando se trata de usar un miembro de $ variablename y esperar que aparezcan las propiedades / métodos de CustomType. Realmente no hay manera de obtener ese comportamiento actualmente.

Answer 3

NOTA: Esta respuesta es un complemento a las otras respuestas.

Para documentar una matriz de objetos puede usar @param ClassName[] $classInstance Description . Pero tenga en cuenta que con PHP 7 puede usar declaraciones de tipo de argumento (sugerencias de tipo) y, en este caso, el tipo debe ser array .

Ejemplo:

CONSEJO: También debe utilizar declare(strict_types=1);

Answer 4

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

Answer 5

Vea los siguientes ejemplos en: 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
*/