¿Cuál es la forma correcta de mostrar un multi-line @param usando PHPDoc?

Question

¿Cuál es la forma correcta de mostrar un multi-line @param usando PHPDoc?

Por lo que he investigado, parece que no puedo encontrar un método correcto para formatear una línea phpdoc @param multilínea. ¿Cuál es la forma recomendada de hacerlo?

Aquí hay un ejemplo:

/**
 * Prints 'Hello World'.
 *
 * Prints out 'Hello World' directly to the output.
 * Can be used to render examples of PHPDoc.
 *
 * @param string $noun Optional. Sends a greeting to a given noun instead.
 *                     Input is converted to lowercase and capitalized.
 * @param bool   $surprise Optional. Adds an exclamation mark after the string.
 */
function helloYou( $noun = 'World', $surprise = false ) {

    $string = 'Hello ' . ucwords( strtolower( $string ) );

    if( !!$surprise ) {
        $string .= '!';
    }

    echo $string;

}

¿Sería eso correcto, o no agregaría sangría, o simplemente mantendría todo en una línea larga?

24

php documentation phpdoc

Author: Sean, 2014-03-21

Source

1 answers

score 21 · Accepted Answer

Simplemente puedes hacerlo de esta manera:

 /**
 *
 * @param string $string Optional. Sends a greeting to a given noun instead.
 *                       Input is converted to lowercase and capitalized.
 * @param bool $surprise
 */
function helloYou( $string = 'World', $surprise = false )
{
    $string = 'Hello ' . ucwords( strtolower( $string ) );

    if( !!$surprise ) {
        $string .= '!';
    }

    echo $string;
}

Así que tu ejemplo está bien excepto por una cosa : el PHPDoc @param necesita tener el mismo nombre que el parámetro PHP. Lo llamaron $sustantivo en el doc y $cadena en el código real.