/test/CodeSniffer/Standards/Xodoa/Sniffs/Commenting/FunctionCommentSniff.php

<?php
/**
 * Parses and verifies the doc comments for functions.
 *
 * PHP version 5
 *
 * @category  PHP
 * @package   PHP_CodeSniffer
 * @author    Greg Sherwood <gsherwood@squiz.net>
 * @author    Marc McIntyre <mmcintyre@squiz.net>
 * @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,v 1.24 2007/11/23 01:04:48 squiz Exp $
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */

if (class_exists('PHP_CodeSniffer_CommentParser_FunctionCommentParser', true) === false) {
	throw new PHP_CodeSniffer_Exception('Class PHP_CodeSniffer_CommentParser_FunctionCommentParser not found');
}

/**
 * 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>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 <gsherwood@squiz.net>
 * @author    Marc McIntyre <mmcintyre@squiz.net>
 * @copyright 2006 Squiz Pty Ltd (ABN 77 084 670 600)
 * @license   http://matrix.squiz.net/developer/tools/php_cs/licence BSD Licence
 * @version   Release: 1.0.1
 * @link      http://pear.php.net/package/PHP_CodeSniffer
 */
class Xodoa_Sniffs_Commenting_FunctionCommentSniff implements PHP_CodeSniffer_Sniff
{

	/**
	 * The name of the method that we are currently processing.
	 *
	 * @var string
	 */
	private $_methodName = '';

	/**
	 * The position in the stack where the fucntion token was found.
	 *
	 * @var int
	 */
	private $_functionToken = null;

	/**
	 * The position in the stack where the class token was found.
	 *
	 * @var int
	 */
	private $_classToken = null;

	/**
	 * The function comment parser for the current method.
	 *
	 * @var PHP_CodeSniffer_Comment_Parser_FunctionCommentParser
	 */
	protected $_commentParser = null;

	/**
	 * The current PHP_CodeSniffer_File object we are processing.
	 *
	 * @var PHP_CodeSniffer_File
	 */
	protected $_currentFile = null;


	/**
	 * 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)
	{
		$find = array(
			T_COMMENT,
			T_DOC_COMMENT,
			T_CLASS,
			T_FUNCTION,
			T_OPEN_TAG,
		);

		$commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1));

		if ($commentEnd === false) {
			return;
		}

		$this->_currentFile = $phpcsFile;
		$tokens            = $phpcsFile->getTokens();

		// If the token that we found was a class or a function, then this
		// function has no doc comment.
		$code = $tokens[$commentEnd]['code'];

		if ($code === T_COMMENT) {
			$error = 'You must use "/**" style comments for a function comment';
			$phpcsFile->addError($error, $stackPtr);
			return;
		} else if ($code !== T_DOC_COMMENT) {
			$phpcsFile->addError('Missing function doc comment', $stackPtr);
			return;
		}

		// If there is any code between the function keyword and the doc block
		// then the doc block is not for us.
		$ignore    = PHP_CodeSniffer_Tokens::$scopeModifiers;
		$ignore[]  = T_STATIC;
		$ignore[]  = T_WHITESPACE;
		$ignore[]  = T_ABSTRACT;
		$ignore[]  = T_FINAL;
		$prevToken = $phpcsFile->findPrevious($ignore, ($stackPtr - 1), null, true);
		if ($prevToken !== $commentEnd) {
			$phpcsFile->addError('Missing function doc comment', $stackPtr);
			return;
		}

		$this->_functionToken = $stackPtr;

		foreach ($tokens[$stackPtr]['conditions'] as $condPtr => $condition) {
			if ($condition === T_CLASS || $condition === T_INTERFACE) {
				$this->_classToken = $condPtr;
				break;
			}
		}

		// If the first T_OPEN_TAG is right before the comment, it is probably
		// a file comment.
		$commentStart = ($phpcsFile->findPrevious(T_DOC_COMMENT, ($commentEnd - 1), null, true) + 1);
		$prevToken    = $phpcsFile->findPrevious(T_WHITESPACE, ($commentStart - 1), null, true);
		if ($tokens[$prevToken]['code'] === T_OPEN_TAG) {
			// Is this the first open tag?
			if ($stackPtr === 0 || $phpcsFile->findPrevious(T_OPEN_TAG, ($prevToken - 1)) === false) {
				$phpcsFile->addError('Missing function doc comment', $stackPtr);
				return;
			}
		}

		$comment           = $phpcsFile->getTokensAsString($commentStart, ($commentEnd - $commentStart + 1));
		$this->_methodName = $phpcsFile->getDeclarationName($stackPtr);

		try {
			$this->_commentParser = new PHP_CodeSniffer_CommentParser_FunctionCommentParser($comment, $phpcsFile);
			$this->_commentParser->parse();
		} catch (PHP_CodeSniffer_CommentParser_ParserException $e) {
			$line = ($e->getLineWithinComment() + $commentStart);
			$phpcsFile->addError($e->getMessage(), $line);
			return;
		}

		$comment = $this->_commentParser->getComment();
		if (is_null($comment) === true) {
			$error = 'Function doc comment is empty';
			$phpcsFile->addError($error, $commentStart);
			return;
		}

		$this->processParams($commentStart);
		$this->processReturn($commentStart, $commentEnd);
		$this->processThrows($commentStart);

		// No extra newline before short description.
		$short        = $comment->getShortComment();
		$newlineCount = 0;
		$newlineSpan  = strspn($short, $phpcsFile->eolChar);
		if ($short !== '' && $newlineSpan > 0) {
			$line  = ($newlineSpan > 1) ? 'newlines' : 'newline';
			$error = "Extra $line found before function comment short description";
			$phpcsFile->addError($error, ($commentStart + 1));
		}

		$newlineCount = (substr_count($short, $phpcsFile->eolChar) + 1);

		// Exactly one blank line between short and long description.
		$long = $comment->getLongComment();
		if (empty($long) === false) {
			$between        = $comment->getWhiteSpaceBetween();
			$newlineBetween = substr_count($between, $phpcsFile->eolChar);
			if ($newlineBetween !== 2) {
				$error = 'There must be exactly one blank line between descriptions in function comment';
				$phpcsFile->addError($error, ($commentStart + $newlineCount + 1));
			}

			$newlineCount += $newlineBetween;
		}

		// Exactly one blank line before tags or no line -> can be used for getters
		$params = $this->_commentParser->getTagOrders();
		if (count($params) > 1) {
			$newlineSpan = $comment->getNewlineAfter();
			if ($newlineSpan !== 2 && $newlineSpan !== 0) {
				$error = 'There must be exactly one blank line before the tags in function comment';
				if ($long !== '') {
					$newlineCount += (substr_count($long, $phpcsFile->eolChar) - $newlineSpan + 1);
				}

				$phpcsFile->addError($error, ($commentStart + $newlineCount));
				$short = rtrim($short, $phpcsFile->eolChar.' ');
			}
		}

	}//end process()


	/**
	 * Process any throw tags that this function comment has.
	 *
	 * @param int $commentStart The position in the stack where the
	 *                          comment started.
	 *
	 * @return void
	 */
	protected function processThrows($commentStart)
	{
		if (count($this->_commentParser->getThrows()) === 0) {
			return;
		}

		foreach ($this->_commentParser->getThrows() as $throw) {

			$exception = $throw->getValue();
			$errorPos  = ($commentStart + $throw->getLine());

			if ($exception === '') {
				$error = '@throws tag must contain the exception class name';
				$this->_currentFile->addError($error, $errorPos);
			}
		}

	}//end processThrows()


	/**
	 * Process the return comment of this function comment.
	 *
	 * @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 processReturn($commentStart, $commentEnd)
	{

	}//end processReturn()


	/**
	 * Process the function parameter comments.
	 *
	 * @param int $commentStart The position in the stack where
	 *                          the comment started.
	 *
	 * @return void
	 */
	protected function processParams($commentStart)
	{
		$realParams = $this->_currentFile->getMethodParameters($this->_functionToken);

		$params      = $this->_commentParser->getParams();
		$foundParams = array();

		if (empty($params) === false) {


			// Parameters must appear immediately after the comment.
			if ($params[0]->getOrder() !== 2) {
				$error    = 'Parameters must appear immediately after the comment';
				$errorPos = ($params[0]->getLine() + $commentStart);
				$this->_currentFile->addError($error, $errorPos);
			}

			$previousParam      = null;
			$spaceBeforeVar     = 10000;
			$spaceBeforeComment = 10000;
			$longestType        = 0;
			$longestVar         = 0;

			foreach ($params as $param) {

				$paramComment = trim($param->getComment());
				$errorPos     = ($param->getLine() + $commentStart);

				// Make sure that there is only one space before the var type.
				if ($param->getWhitespaceBeforeType() !== ' ') {
					$error = 'Expected 1 space before variable type';
					$this->_currentFile->addError($error, $errorPos);
				}

				$spaceCount = substr_count($param->getWhitespaceBeforeVarName(), ' ');
				if ($spaceCount < $spaceBeforeVar) {
					$spaceBeforeVar = $spaceCount;
					$longestType    = $errorPos;
				}

				$spaceCount = substr_count($param->getWhitespaceBeforeComment(), ' ');

				if ($spaceCount < $spaceBeforeComment && $paramComment !== '') {
					$spaceBeforeComment = $spaceCount;
					$longestVar         = $errorPos;
				}

				// Make sure they are in the correct order,
				// and have the correct name.
				$pos = $param->getPosition();

				$paramName = ($param->getVarName() !== '') ? $param->getVarName() : '[ UNKNOWN ]';


				// Make sure the names of the parameter comment matches the
				// actual parameter.
				if (isset($realParams[($pos - 1)]) === true) {
					$realName      = $realParams[($pos - 1)]['name'];
					$foundParams[] = $realName;
					// Append ampersand to name if passing by reference.
					if ($realParams[($pos - 1)]['pass_by_reference'] === true) {
						$realName = '&'.$realName;
					}

					if ($realName !== $param->getVarName()) {
						$error  = 'Doc comment var "'.$paramName;
						$error .= '" does not match actual variable name "'.$realName;
						$error .= '" at position '.$pos;

						$this->_currentFile->addError($error, $errorPos);
					}
				} else {
					// We must have an extra parameter comment.
					// Ignore..
					//$error = 'Superfluous doc comment at position '.$pos;
					//$this->_currentFile->addError($error, $errorPos);
				}

				if ($param->getVarName() === '') {
					$error = 'Missing parameter name at position '.$pos;
					$this->_currentFile->addError($error, $errorPos);
				}

				if ($param->getType() === '') {
					$error = 'Missing type at position '.$pos;
					$this->_currentFile->addError($error, $errorPos);
				}

				if ($paramComment === '') {
					//$error = 'Missing comment for param "'.$paramName.'" at position '.$pos;
					//$this->_currentFile->addError($error, $errorPos);
				}

				$previousParam = $param;

			}//end foreach

			if ($spaceBeforeVar !== 1 && $spaceBeforeVar !== 10000 && $spaceBeforeComment !== 10000) {
				$error = 'Expected 1 space after the longest type';
				$this->_currentFile->addError($error, $longestType);
			}

			if ($spaceBeforeComment !== 1 && $spaceBeforeComment !== 10000) {
				$error = 'Expected 1 space after the longest variable name';
				$this->_currentFile->addError($error, $longestVar);
			}

		}//end if

		$realNames = array();
		foreach ($realParams as $realParam) {
			$realNames[] = $realParam['name'];
		}

		// Report and missing comments.
		$diff = array_diff($realNames, $foundParams);
		foreach ($diff as $neededParam) {
			if (count($params) !== 0) {
				$errorPos = ($params[(count($params) - 1)]->getLine() + $commentStart);
			} else {
				$errorPos = $commentStart;
			}

			$error = 'Doc comment for "'.$neededParam.'" missing';
			$this->_currentFile->addError($error, $errorPos);
		}

	}//end processParams()


}//end class