Description: ------------ Hello, if I have a valid page-level docblock, and after this I have a function without a function docblock, the page-level docblock is now reported as a wrong function docblock. The test script with 2 classes works correct. Regards, Carsten Test script: --------------- <?php /** * Description * * PHP versions 5 * * @category Foo * @package Foo_Bar * @author Doe <doe@example.org> * @license http://www.php.net/license/3_0.txt PHP * @version CVS: $Id: test.php,v 0.00 2007/10/24 00:00:00 doe Exp $ * @link http://pear.php.net/package/Foo_Bar */ function test($foo) { } function test2($bar) { } ?> Expected result: ---------------- FILE: /foo/bar/test.php ---------------------------------------------------------------- FOUND 2 ERROR(S) AND 0 WARNING(S) AFFECTING 2 LINE(S) ---------------------------------------------------------------- 15 | ERROR | Missing function doc comment 19 | ERROR | Missing function doc comment ---------------------------------------------------------------- Actual result: -------------- FILE: /foo/bar/test.php ---------------------------------------------------------------- FOUND 3 ERROR(S) AND 5 WARNING(S) AFFECTING 8 LINE(S) ---------------------------------------------------------------- 2 | ERROR | Doc comment for "$foo" missing 7 | WARNING | @category tag is not allowed in function comment 8 | WARNING | @package tag is not allowed in function comment 9 | WARNING | @author tag is not allowed in function comment 10 | WARNING | @license tag is not allowed in function comment 11 | WARNING | @version tag is not allowed in function comment 13 | ERROR | Missing @return tag in function comment 19 | ERROR | Missing function doc comment ----------------------------------------------------------------

Thank you for taking the time to write to us, but this is not a bug. This is the expected behavior. Both doc blocks look the same, so PHP_CodeSniffer can't tell the difference. That particular sniff in the PEAR standard makes the assumption that the first comment above functions and classes belongs to that keyword. Once you put a second doc block, there is no longer any need for assumptions and the sniff will work fine.

Hi Greg, > This is the expected behavior. in my case it was one little helper function around line 200 (which I have forgotten), and I was wondering why phpcs reports an error in line 2 and what's wrong with my page-level docblock (I have no other classes or functions in this file). If you replace in the testscript the 2 functions with: | class Test() | { | } | | class Test2() | { | } the output is correct: | 15 | ERROR | Missing class doc comment | 19 | ERROR | Missing class doc comment > Once you put a second doc block, there is no longer any > need for assumptions and the sniff will work fine. Yes and no. If I insert this docblock after the page-level docblock: | /** | * global variable | * @global integer $GLOBALS['_foo'] | * @name $_foo | */ | $GLOBALS['_foo'] = 0; the output is: | 15 | ERROR | Doc comment for "$foo" missing | 17 | ERROR | There must be exactly one blank line before the tags in function | | | comment | 19 | ERROR | Missing @return tag in function comment | 26 | ERROR | Missing function doc comment Better, but not 100% correct. > Both doc blocks look the same, so PHP_CodeSniffer can't > tell the difference. I think, the first docblock must be the page-level docblock and can't be the docblock for something else. Maybe this situation is difficult to sniff? Then the status should be "Won't fix". Regards, Carsten

> in my case it was one little helper function > around line 200 This is something I can fix. If there is other code between the function and the located doc block, it is fair to assume that the doc block does not belong to the function. I'll make that change. > Yes and no. The solution for the above problem should fix this too. > I think, the first docblock must be the page-level > docblock and can't be the docblock for something else. I think the change I'm going to make should remove some ambiguity, but if you have a single doc block and then a class or function, CodeSniffer is still going to have to make an assumption either way. It doesn't really matter which assumption is made because both show errors.

This bug has been fixed in CVS. If this was a documentation problem, the fix will appear on pear.php.net by the end of next Sunday (CET). If this was a problem with the pear.php.net website, the change should be live shortly. Otherwise, the fix will appear in the package's next release. Thank you for the report and for helping us make PEAR better. I've changed the rules of the sniffs a bit. A file doc block is not considered a function doc block if there is code between the doc block and the function, or if it follows the first PHP open tag.