1

I am writing a script in the procedural PHP style, but still want to document everything the best I can. Thats why I use DocBlock comments. Being new to them, I wonder how to use them in the following scenario (code written especially for this question):

/**
 * Checks string length
 *
 * @param int $max_length  an integer determining the string length to check against
 * @param string $string  the string to be checked
 * @return bool  a boolean value indicating if the string is shorter or longer
 *               than $max_length. True if shorter, false if longer
 */
function check_length( $max_length = 2, $string ) {
    $i = 0;

    if( strlen( $string ) > $max_length )
        return false;

    return true;
}

Lets assume $i would be needed for that function. How should I document it? I can't put it inside the function DocBlock because its not an argument.

The example has two similar vars inside that class, but as I am not writing object oriented code, I can't put $i outside the function (or just don't want to change my coding style to be able to use DocBlocks).

Another approach would be to not document these 'internal' variables because for using the function, they are not important.

mzjn
  • 48,958
  • 13
  • 128
  • 248
Sven
  • 12,997
  • 27
  • 90
  • 148
  • I don't see the point of your `$i` variable. Eitherway, if `$i` was important, or whatnot, I'd either include a short explanation within the docblock (under the title), OR to an inline comment to explain what the purpose of `$i` is for. Also, you must have required arguments before optional arguments. In your example, you cannot have `$string` after `$max_length = 2`. They should be placed the other way around, or give `$string` a default value. – Phil Cross Apr 12 '14 at 20:08

1 Answers1

1

The PHP-Doc-Comments could be seen as API doc of your module/class/whatever. Since $i is uninteresting to the user of your code - why would you put it into your API doc? Your users don't need to know about it and thus you shouldn't tell them. $i might be interesting to someone actually reading or reviewing your code. Thus you should add a simple one-line comment (//) describing what $i is/does or a multi-line comment if needed.

m02ph3u5
  • 3,022
  • 7
  • 38
  • 51