phpdoc standard for setting default value of an optional parameter?

Question

Example:

/**
 * This function will determine whether or not one string starts with another string.
 * @param string $haystack <p>The string that needs to be checked.</p>
 * @param string $needle <p>The string that is being checked for.</p>
 * @param boolean $case[optional] <p>Set to false to ignore case(capital or normal characters)</p>
 * @return boolean <p>If the $haystack string does start with the $needle string, the return will be true. False if not.</p>
 */
function endsWith($haystack,$needle,$case=true) {
    if($case){return (strcmp(substr($haystack, strlen($haystack) - strlen($needle)),$needle)===0);}
    return (strcasecmp(substr($haystack, strlen($haystack) - strlen($needle)),$needle)===0);
}

The optional parameter is set to true by default. I wish to indicate what the default setting is in the documentation. Is there a standard way of doing this or do I have to mention it in the description?

karim79 · Accepted Answer · 2009-09-07 01:12:29Z

22

The doc says:

Note that the $paramname,... will be shown in the output docs in both the parameter listing AND the function signature. If you are not indicating in the actual code that the parameter is optional (via "$paramname = 'a default value'"), then you should mention in the parameter's description that the parameter is optional.

So if you're not showing the default assignment in the function signature, it would be a good idea to include it in the description, but in your case you are including it in the signature. So, you don't need to change a thing unless doing so would make you feel better.

edited Sep 7, 2009 at 1:12

answered Sep 6, 2009 at 22:41

karim79

343k67 gold badges420 silver badges409 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

KdgDev Over a year ago

Thanks. And it does make me feel somewhat better, yes :)

FreeLightman Over a year ago

This is the answer in case when an optional param is included in function signature. But what if it is not? How to document an optional parameter? As from docs the only way is to tell it in description. So there is no way to write for example [$case=true]. Even jsdoc has it.

Collectives™ on Stack Overflow

phpdoc standard for setting default value of an optional parameter?

1 Answer 1

2 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

2 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related