32

From what I've done research on, I can't seem to find a correct method to format a multiline phpdoc @param line. What is the recommended way to do so?

Here's an example:

/**
 * 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;

}

Would that be correct, or would you not add indentation, or would you just keep everything on one, long line?

Sean
  • 2,173
  • 21
  • 42
  • Why do you want it to be multiline? Keep it on one longer line, if you need to describe in more detail do it after the @params – Dany Caissy Mar 21 '14 at 14:39
  • 4
    I wouldn't want to keep it all on one line as it would get increasingly harder to read the longer it would get. I'm also not sure what you mean regarding your second choice. – Sean Mar 21 '14 at 14:47
  • 1
    I think doc generators that parse the tags won't care about that indention, so it really only matters how you want to see it when directly looking at the code and docblock. Some coding standards do dictate indention though, e.g. PEAR standard says datatypes should align, varnames should align, and descriptions should align. So, in your example, the datatypes and varnames are aligned to the standard, but the description for $noun should be indented further, to be aligned with the description for $surprise. A simpler option is put the whole description on the next line, with a 4-space indent. – ashnazg Mar 31 '14 at 15:20
  • 2
    NB: PSR-2 will complain about too long lines, even in comment blocks. – Olle Härstedt Feb 06 '17 at 15:02

1 Answers1

29

You can simply do it this way : 

 /**
 *
 * @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;
}

So your example is fine except for one thing : the PHPDoc @param needs to have the same name as the PHP parameter. You called it $noun in the doc and $string in the actual code.

Dany Caissy
  • 3,118
  • 12
  • 20