Declaring lots of variables for phpdoc without starting each with /**

3
votes

I have objects with many variables that I declare and explain in the comments. I am commenting very thoroughly for later processing using phpDoc, however I have no experience with actually compiling the documentation yet.

I find it very annoying that with phpDoc notation, each variable eats up four to six lines of code even if the only attribute I want to set is the description:

/**
 * @desc this is the description
 */

 var $variable = null;

I would like to use the following notation:

# @desc this is the description
var $variable = null;

is there a simple way to tweak phpDoc into accepting this, or will it give me trouble when I actually try to compile documentation out of it? I don't need the tweak now (although it's appreciated of course), just a statement from somebody who knows phpDoc whether this is feasible without having to re-engineer large parts of its code.

2
phpdocumentationphpdoc

2 Answers

12
votes

Just write one-line docblocks

/** @desc this is the description */
var $variable = null;

Problem solved.

2
votes

In addition to what Frank Farmer mentioned (+1 to his solution),

/** is declared as T_DOC_COMMENT in the PHP tokenizer since PHP 5. This means to say that documentation notation are all parsed from /** to */.

You can't just use # or /* to write your PHP documentations.

See:

http://www.php.net/manual/en/tokens.php