More changes to comment sniffs in the Squiz standard to make them mor…

…e generic by pushing some product-specific code to the MySource standard

git-svn-id: http://svn.php.net/repository/pear/packages/PHP_CodeSniffer/trunk@302088 c90b9560-bf6c-de11-be94-00142212c4b1

CodeSniffer/Standards/MySource/Sniffs/Commenting/FunctionCommentSniff.php

@@ -0,0 +1,109 @@
+<?php
+/**
+ * Parses and verifies the doc comments for functions.
+ *
+ * PHP version 5
+ *
+ * @category  PHP
+ * @package   PHP_CodeSniffer
+ * @author    Greg Sherwood <[email protected]>
+ * @author    Marc McIntyre <[email protected]>
+ * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
+ * @version   CVS: $Id: FunctionCommentSniff.php 302056 2010-08-10 03:47:09Z squiz $
+ * @link      http://pear.php.net/package/PHP_CodeSniffer
+ */
+
+if (class_exists('Squiz_Sniffs_Commenting_FunctionCommentSniff', true) === false) {
+    $error = 'Class Squiz_Sniffs_Commenting_FunctionCommentSniff not found';
+    throw new PHP_CodeSniffer_Exception($error);
+}
+
+/**
+ * Parses and verifies the doc comments for functions.
+ *
+ * Same as the Squiz standard, but adds support for API tags.
+ *
+ * @category  PHP
+ * @package   PHP_CodeSniffer
+ * @author    Greg Sherwood <[email protected]>
+ * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
+ * @version   Release: @package_version@
+ * @link      http://pear.php.net/package/PHP_CodeSniffer
+ */
+class MySource_Sniffs_Commenting_FunctionCommentSniff extends Squiz_Sniffs_Commenting_FunctionCommentSniff
+{
+
+
+    /**
+     * Process a list of unknown tags.
+     *
+     * @param int $commentStart The position in the stack where the comment started.
+     * @param int $commentEnd   The position in the stack where the comment ended.
+     *
+     * @return void
+     */
+    protected function processUnknownTags($commentStart, $commentEnd)
+    {
+        $unknownTags = $this->commentParser->getUnknown();
+        $words       = $this->commentParser->getWords();
+        $hasApiTag   = false;
+        foreach ($unknownTags as $errorTag) {
+            $pos = $errorTag['pos'];
+            if ($errorTag['tag'] === 'api') {
+                if ($hasApiTag === true) {
+                    // We've come across an API tag already, which means
+                    // we were not the first tag in the API list.
+                    $error = 'The @api tag must come first in the @api tag list in a function comment';
+                    $this->currentFile->addError($error, ($commentStart + $errorTag['line']), 'ApiNotFirst');
+                }
+
+                $hasApiTag = true;
+
+                // There needs to be a blank line before the @api tag.
+                // So expect a single space before the tag, then 2 newlines before
+                // that, then some content.
+                if (trim($words[($pos - 2)]) !== ''
+                    || strpos($words[($pos - 2)], $this->currentFile->eolChar) === false
+                    || strpos($words[($pos - 3)], $this->currentFile->eolChar) === false
+                    || trim($words[($pos - 4)]) === ''
+                ) {
+                    $error = 'There must be one blank line before the @api tag in a function comment';
+                    $this->currentFile->addError($error, ($commentStart + $errorTag['line']), 'ApiSpacing');
+                }
+            } else if (substr($errorTag['tag'], 0, 4) === 'api-') {
+                $hasApiTag = true;
+                if (trim($words[($pos - 2)]) !== ''
+                    || strpos($words[($pos - 2)], $this->currentFile->eolChar) === false
+                    || trim($words[($pos - 3)]) === ''
+                ) {
+                    $error = 'There must be no blank line before the @%s tag in a function comment';
+                    $data  = array($errorTag['tag']);
+                    $this->currentFile->addError($error, ($commentStart + $errorTag['line']), 'ApiTagSpacing', $data);
+                }
+            } else {
+                $error = '@%s tag is not allowed in function comment';
+                $data  = array($errorTag['tag']);
+                $this->currentFile->addWarning($error, ($commentStart + $errorTag['line']), 'TagNotAllowed', $data);
+            }
+        }
+
+        if ($hasApiTag === true) {
+            // API tags must be the last tags in a function comment.
+            $order = $this->commentParser->getTagOrders();
+            $lastTag = array_pop($order);
+            if ($lastTag !== 'api'
+                && substr($lastTag, 0, 4) !== 'api-'
+            ) {
+                $error = 'The @api tags must be the last tags in a function comment';
+                $this->currentFile->addError($error, $commentEnd, 'ApiNotLast');
+            }
+        }
+
+    }//end processUnknownTags
+
+
+}//end class
+
+?>

CodeSniffer/Standards/MySource/Tests/Commenting/FunctionCommentUnitTest.inc

@@ -0,0 +1,71 @@
+<?php
+/**
+ * Short content.
+ *
+ * @return void
+ *
+ * @api           read
+ * @api-privilege asset.read.content
+ * @api-mustlock  false
+ */
+private function functionCall() {}
+
+/**
+ * Short content.
+ *
+ * @return void
+ *
+ * @api read
+ */
+private function functionCall() {}
+
+/**
+ * Short content.
+ *
+ * @api read
+ *
+ * @return void
+ */
+private function functionCall() {}
+
+/**
+ * Short content.
+ *
+ * @return void
+ *
+ * @api-privilege asset.read.content
+ * @api           read
+ * @api-mustlock  false
+ */
+private function functionCall() {}
+
+/**
+ * Short content.
+ *
+ * @return void
+ *
+ * @api           read
+ *
+ * @api-privilege asset.read.content
+ * @api-mustlock  false
+ */
+private function functionCall() {}
+
+/**
+ * Short content.
+ *
+ * @return void
+ * @api read
+ */
+private function functionCall() {}
+
+/**
+ * Test unknown tags.
+ *
+ * @return  void
+ * @since   read
+ * @hello   hello
+ * @package Test
+ */
+private function functionCall() {}
+?>

CodeSniffer/Standards/MySource/Tests/Commenting/FunctionCommentUnitTest.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Unit test class for FunctionCommentSniff.
+ *
+ * PHP version 5
+ *
+ * @category  PHP
+ * @package   PHP_CodeSniffer
+ * @author    Greg Sherwood <[email protected]>
+ * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
+ * @version   CVS: $Id: FunctionCommentUnitTest.php 292513 2009-12-23 00:41:20Z squiz $
+ * @link      http://pear.php.net/package/PHP_CodeSniffer
+ */
+
+/**
+ * Unit test class for FunctionCommentSniff.
+ *
+ * @category  PHP
+ * @package   PHP_CodeSniffer
+ * @author    Greg Sherwood <[email protected]>
+ * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
+ * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
+ * @version   Release: @package_version@
+ * @link      http://pear.php.net/package/PHP_CodeSniffer
+ */
+class MySource_Tests_Commenting_FunctionCommentUnitTest extends AbstractSniffUnitTest
+{
+
+
+    /**
+     * Returns the lines where errors should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of errors that should occur on that line.
+     *
+     * @return array(int => int)
+     */
+    public function getErrorList()
+    {
+        return array(
+                28 => 1,
+                36 => 1,
+                37 => 2,
+                49 => 1,
+                58 => 1,
+                65 => 1,
+               );
+
+    }//end getErrorList()
+
+
+    /**
+     * Returns the lines where warnings should occur.
+     *
+     * The key of the array should represent the line number and the value
+     * should represent the number of warnings that should occur on that line.
+     *
+     * @return array(int => int)
+     */
+    public function getWarningList()
+    {
+        return array(
+                67 => 1,
+                68 => 1,
+               );
+
+    }//end getWarningList()
+
+
+}//end class
+
+?>

CodeSniffer/Standards/MySource/ruleset.xml

@@ -2,7 +2,9 @@
 <ruleset name="MySource">
  <description>The MySource coding standard builds on the Squiz coding standard. Currently used for MySource Mini development.</description>
 
- <!-- Include the whole Squiz standard -->
- <rule ref="Squiz"/>
+ <!-- Include the whole Squiz standard except FunctionComment, which we override -->
+ <rule ref="Squiz">
+  <exclude name="Squiz.Commenting.FunctionComment"/>
+ </rule>
 
 </ruleset>

CodeSniffer/Standards/Squiz/Sniffs/Commenting/ClassCommentSniff.php

@@ -228,13 +228,25 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
             $phpcsFile->addError($error, ($commentStart + 1), 'ShortFullStop');
         }
 
-        // Check for unknown/deprecated tags.
-        $unknownTags = $this->commentParser->getUnknown();
-        foreach ($unknownTags as $errorTag) {
+        // No tags are allowed in the class comment.
+        $tags = $this->commentParser->getTags();
+        foreach ($tags as $errorTag) {
             $error = '@%s tag is not allowed in class comment';
             $data  = array($errorTag['tag']);
             $phpcsFile->addWarning($error, ($commentStart + $errorTag['line']), 'TagNotAllowed', $data);
-            return;
+        }
+
+        // The last content should be a newline and the content before
+        // that should not be blank. If there is more blank space
+        // then they have additional blank lines at the end of the comment.
+        $words   = $this->commentParser->getWords();
+        $lastPos = (count($words) - 1);
+        if (trim($words[($lastPos - 1)]) !== ''
+            || strpos($words[($lastPos - 1)], $this->currentFile->eolChar) === false
+            || trim($words[($lastPos - 2)]) === ''
+        ) {
+            $error = 'Additional blank lines found at end of class comment';
+            $this->currentFile->addError($error, $commentEnd, 'SpacingAfter');
         }
 
     }//end process()