Commenting if statements for phpdocumentor2

Question

I am in the process of documenting a PHP project using PHPDocumentor2. Ironically, PHPDoc's documentation isn't overly detailed. I fully understand how to comment files, classes, functions and variables, however if a variable or constant is being defined within an if statement how should I comment it?

Example:

if ($foo==$bar) {
    define('FOOBAR',$foo);
} else if ($foo>$bar) {
    define('FOOBAR',$bar);
} else {
    define('FOOBAR',$foo+$bar);
}

Clearly I don't want to add 3 comments, and the documentation should really explain the if statement so logically the docBlock ought to go before the start of the if statement - this would be most aesthetically pleasing in code view - but the docBlock has to be on the line immediately before the "define". I can put it before the first one, but that looks odd.

if ($foo==$bar) {
    /**
     * FOOBAR Definition.
     *
     * Value of FOOBAR. Yada yada.
     * @var int
     */
    define('FOOBAR',$foo);
} else if ($foo>$bar) {
    define('FOOBAR',$bar);
} else {
    define('FOOBAR',$foo+$bar);
}

Any ideas?

score 0 · Answer 1 · answered Aug 29 '12 at 14:34

It's possible that phpdoc2's expectation of @ignore behavior is different that phpdoc1's.

In phpdoc1, the @ignore tag effectively means "you see this next piece of code that contains a documentable element in it? just ignore that piece of code". This behavior did indeed allow for PandyLegend's example to work exactly as the code+docblocks are written above. The manual's example usage for @ignore actually matches PandyLegend's use case too (http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.ignore.pkg.html).

Judging from phpdoc2's behavior I see from using PandyLegend's example, I think phpdoc2 is thinking "you see the documentable element in this next piece of code? record its name, and ignore that element completely in this whole set of documentation".

My guess is that this issue really is just a different interpretation rather than a bug.

(https://github.com/phpDocumentor/phpDocumentor2/issues/583)

Commenting if statements for phpdocumentor2

1 Answers1