WordPress_Sniffs_Commenting_FunctionCommentSniff

FunctionCommentSniff.php

<?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-2014 Squiz Pty Ltd (ABN 77 084 670 600)
 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */

/**
 * Parses and verifies the doc comments for functions.
 *
 * Verifies that :
 * <ul>
 *  <li>A comment exists</li>
 *  <li>There is a blank newline after the short description.</li>
 *  <li>There is a blank newline between the long and short description.</li>
 *  <li>There is a blank newline between the long description and tags.</li>
 *  <li>Parameter names represent those in the method.</li>
 *  <li>Parameter comments are in the correct order</li>
 *  <li>Parameter comments are complete</li>
 *  <li>A space is present before the first and after the last parameter</li>
 *  <li>A return type exists</li>
 *  <li>There must be one blank line between body and headline comments.</li>
 *  <li>Any throw tag must have an exception class.</li>
 * </ul>
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Greg Sherwood <[email protected]>
 * @author    Marc McIntyre <[email protected]>
 * @copyright 2006-2014 Squiz Pty Ltd (ABN 77 084 670 600)
 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class WordPress_Sniffs_Commenting_FunctionCommentSniff implements PHP_CodeSniffer_Sniff
{


	/**
	 * Returns an array of tokens this test wants to listen for.
	 *
	 * @return array
	 */
	public function register()
	{
		return array(T_FUNCTION);

	}//end register()


	/**
	 * Processes this test, when one of its tokens is encountered.
	 *
	 * @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
	 * @param int                  $stackPtr  The position of the current token
	 *                                        in the stack passed in $tokens.
	 *
	 * @return void
	 */
	public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
	{
		$tokens = $phpcsFile->getTokens();
		$find   = PHP_CodeSniffer_Tokens::$methodPrefixes;
		$find[] = T_WHITESPACE;

		$commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1), null, true);
		if ($tokens[$commentEnd]['code'] === T_COMMENT) {
			// Inline comments might just be closing comments for
			// control structures or functions instead of function comments
			// using the wrong comment type. If there is other code on the line,
			// assume they relate to that code.
			$prev = $phpcsFile->findPrevious($find, ($commentEnd - 1), null, true);
			if ($prev !== false && $tokens[$prev]['line'] === $tokens[$commentEnd]['line']) {
				$commentEnd = $prev;
			}
		}

		if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
		    && $tokens[$commentEnd]['code'] !== T_COMMENT
		) {
			$phpcsFile->addError('Missing function doc comment', $stackPtr, 'Missing');
			$phpcsFile->recordMetric($stackPtr, 'Function has doc comment', 'no');
			return;
		} else {
			$phpcsFile->recordMetric($stackPtr, 'Function has doc comment', 'yes');
		}

		if ($tokens[$commentEnd]['code'] === T_COMMENT) {
			$phpcsFile->addError('You must use "/**" style comments for a function comment', $stackPtr, 'WrongStyle');
			return;
		}

		if ($tokens[$commentEnd]['line'] !== ($tokens[$stackPtr]['line'] - 1)) {
			$error = 'There must be no blank lines after the function comment';
			$phpcsFile->addError($error, $commentEnd, 'SpacingAfter');
		}

		// assert since as given and ("x.x.x" or "MU")
		$commentStart = $tokens[$commentEnd]['comment_opener'];
		foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
			if ($tokens[$tag]['content'] === '@since') {
				// Make sure the tag isn't empty.
				$string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $tag, $commentEnd);
				if ($string === false || $tokens[$string]['line'] !== $tokens[$tag]['line']) {
					$error = 'Content missing for @since tag in function comment';
					$phpcsFile->addError($error, $tag, 'EmptySince');
				}

				// Make sure tag is "x.x.x" or "MU"
				$content = $tokens[ $string ]['content'];
				if (preg_replace('/\d+\.\d+\.\d+/', '', $content ) !== ''
				&& $content != 'MU')
				{
					$phpcsFile->addError(
						'Since is not in format x.x.x or "MU"',
						$tag,
						'WrongSinceFormat'
					);
				}

			}
		}

		//$this->processReturn($phpcsFile, $stackPtr, $commentStart);
		//$this->processThrows($phpcsFile, $stackPtr, $commentStart);
		//$this->processParams($phpcsFile, $stackPtr, $commentStart);

	}//end process()

}//end class

FunctionCommentUnitTest.inc

<?php

/**
 * Short description.
 *
 * Long
 * Description.
 *
 * @since 2.0.0
 */
function clean() {} // good.

/**
 * Short description.
 *
 * Long
 * description.
 *
 * @since 2
 */
function since_version_very_short() {} // Bad.

/**
 * Short description.
 *
 * Long description.
 * Is very long.
 *
 * @since 2.0
 */
function since_version_short() {} // Bad.

/**
 * Short description.
 *
 * Long description.
 * Is very long.
 *
 * @since 2.0.0.0
 */
function since_version_long() {} // Bad.

/**
 * Short description.
 *
 * Long description.
 * Is very long.
 *
 * @since 2.0.0-alpha
 */
function since_version_is_alphanumeric() {} // Bad.

WordPress_Tests_Commenting_FunctionCommentUnitTest.php

<?php
/**
 * Unit test class for the Function sniff.
 *
 * PHP version 5
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Akeda Bagus <[email protected]>
 * @author    Greg Sherwood <[email protected]>
 * @author    Marc McIntyre <[email protected]>
 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */

/**
 * Unit test class for the Function sniff.
 *
 * A sniff unit test checks a .inc file for expected violations of a single
 * coding standard. Expected errors and warnings are stored in this class.
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Akeda Bagus <[email protected]>
 * @author    Greg Sherwood <[email protected]>
 * @author    Marc McIntyre <[email protected]>
 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
 * @version   Release: @package_version@
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class WordPress_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(
	        19 => 1,
	        29 => 1,
	        39 => 1,
	        49 => 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();

    }//end getWarningList()


}//end class

?>