example - phpdocumentor download windows

PHPDoc: Documentar una función con un número variable de argumentos

Question

¿Cuál es el método recomendado para documentar un método de clase que acepta un número variable de argumentos?

Tal vez algo como esto?

<?php

class Foo {
    /**
     * Calculates the sum of all the arguments.
     *
     * @param mixed [$arg1, $arg2, ...]
     *
     * @return float the calculated sum
     */
    public static function sum() {
        return array_sum(func_get_args());
    }
}

Nota: como regla general, imagino que este tipo de cosas deben evitarse siempre que sea posible. Dicho esto, sería bueno documentar los pocos casos restantes en los que no se puede evitar.

Answer 1

Algo que vale la pena notar es que con un bloque de documentos como:

/**
 * @param Type[] ...$values One or more values.
 */
public function func(Type ...$values) {
    // ...
}

... puede parecer que puedes pasar una matriz de Type , por ejemplo,

Foo()->func([Type, Type, Type])

... esto arroja un error fatal, obviamente ahora.

Dónde:

Foo()->func(...[Type, Type, Type])

... no como lo has desestructurado en el método de llamada.

De todos modos, el punto aquí es que estaba experimentando cómo PHPStorm trataría el bloque de documentos y dependiendo de la manera en que orientas tu variable $args en tu bloque de documentos, ya sea con ...$args o $args,... determina el tipo de pistas que recibe en su IDE.

Realmente me gustaría una manera de sugerir los valores que debe pasar por nombre al método en la imagen ejemplificada a continuación, en el caso de que tenga una longitud opcional de parámetros de función / método, con un orden específico en el que deben pasarse.

Podría pensar que, "simplemente configure los argumentos predeterminados, $arg1 = ''default'', $arg2 = true ", lo que normalmente tiene sentido, pero en los casos

Pseudo-ejemplo:

/**
 * @param int ...$args Hour, Minute, Second, Timezone, $arg [, ...$args]
 */
public static function createA(int ...$args) {}

/**
 * @param int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args]
 */
public static function createB(int ...$args) {}

/**
 * @param int[]|int $args,... Hour, Minute, Second, Timezone, $arg [, ...$args]
 */

public static function createC(int ...$args) {}

... así que cualquiera de

• https://stackoverflow.com/a/38275992/1290575
• https://stackoverflow.com/a/43622600/1290575

... es la respuesta correcta (teniendo en cuenta la orientación: ...$args o $args,... )

Answer 2

En el caso de la ... sintaxis , PHPStorm 2017.1 utiliza:

/**
 * @param Type[] ...$values One or more values.
 */
public function func(Type ...$values) {
    // ...
}

Answer 3

Si usa un número variable de argumentos y también usa PHP >= 5.6 entonces puede usar varias funciones (permitiendo un número variable de argumentos) que aún se ajustan a la sintaxis de PHPDoc ,... ya mencionada y PHPStorm interpretará los documentos correctamente también. El uso de funciones variadic elimina la necesidad de func_get_args() para capturar argumentos en una matriz.

/**
 * @param mixed $args,... Explainatorium!
 */
function variadiculous(...$args) {
    // NOTE: $args === func_get_args()
    foreach ( $args as $arg ) {
        /* do work */
    }
}

PHPStorm generará automáticamente los documentos como @param array $args porque, técnicamente, cuando está dentro de la función variadiculous is_array($args) es verdadero. Lo cambio para leer @param mixed $args,... como arriba y cuando uso la tecla de acceso rápido para mostrar una firma de función de otro lugar en mi código, PHPStorm muestra variadiculous($args : ...array|mixed) - I Recomiendo usar este método si usas PHP> = 5.6

Answer 4

/**
 * @param mixed $numbers,... Description
 */
Public function sum ($numbers)

En el método, $ números no serán utilizados.