35

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?

4
  • 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 Mar 21, 2014 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, 2014 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, 2014 at 15:20
  • 2
    NB: PSR-2 will complain about too long lines, even in comment blocks. Feb 6, 2017 at 15:02

1 Answer 1

32

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.

1
  • 1
    Good spot on the incorrect param name match. Thanks for that!
    – Sean
    Mar 21, 2014 at 15:10

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.