Merge pull request #36 from Zenify/own-return-function-comment-sniff

use own MethodCommentReturnTag sniff, ref #30

src/ZenifyCodingStandard/Helper/Commenting/MethodDocBlock.php

@@ -0,0 +1,56 @@
+<?php
+
+/**
+ * This file is part of Zenify
+ * Copyright (c) 2012 Tomas Votruba (http://tomasvotruba.cz)
+ */
+
+namespace ZenifyCodingStandard\Helper\Commenting;
+
+use PHP_CodeSniffer_File;
+
+
+final class MethodDocBlock
+{
+
+	/**
+	 * @param PHP_CodeSniffer_File $file
+	 * @param int $position
+	 * @return bool
+	 */
+	public static function hasMethodDocBlock(PHP_CodeSniffer_File $file, $position)
+	{
+		$tokens = $file->getTokens();
+		$currentToken = $tokens[$position];
+		$docBlockClosePosition = $file->findPrevious(T_DOC_COMMENT_CLOSE_TAG, $position);
+
+		if ($docBlockClosePosition === FALSE) {
+			return FALSE;
+		}
+
+		$docBlockCloseToken = $tokens[$docBlockClosePosition];
+		if ($docBlockCloseToken['line'] === ($currentToken['line'] - 1)) {
+			return TRUE;
+		}
+
+		return FALSE;
+	}
+
+
+	/**
+	 * @param PHP_CodeSniffer_File $file
+	 * @param int $position
+	 * @return string
+	 */
+	public static function getMethodDocBlock(PHP_CodeSniffer_File $file, $position)
+	{
+		if ( ! self::hasMethodDocBlock($file, $position)) {
+			return '';
+		}
+
+		$commentStart = $file->findPrevious(T_DOC_COMMENT_OPEN_TAG, $position - 1);
+		$commentEnd = $file->findPrevious(T_DOC_COMMENT_CLOSE_TAG, $position - 1);
+		return $file->getTokensAsString($commentStart, $commentEnd - $commentStart + 1);
+	}
+
+}

src/ZenifyCodingStandard/Sniffs/Commenting/MethodCommentReturnTagSniff.php

@@ -0,0 +1,91 @@
+<?php
+
+/**
+ * This file is part of Zenify
+ * Copyright (c) 2012 Tomas Votruba (http://tomasvotruba.cz)
+ */
+
+namespace ZenifyCodingStandard\Sniffs\Commenting;
+
+use PHP_CodeSniffer_File;
+use PHP_CodeSniffer_Sniff;
+use ZenifyCodingStandard\Helper\Commenting\MethodDocBlock;
+
+
+/**
+ * Rules:
+ * - Getters should have @return tag (except {@inheritdoc}).
+ */
+final class MethodCommentReturnTagSniff implements PHP_CodeSniffer_Sniff
+{
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function register()
+	{
+		return [T_FUNCTION];
+	}
+
+
+	/**
+	 * @var string[]
+	 */
+	private $getterMethodPrefixes = ['get', 'is', 'has', 'will', 'should'];
+
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function process(PHP_CodeSniffer_File $file, $position)
+	{
+		$methodName = $file->getDeclarationName($position);
+		$isGetterMethod = $this->guessIsGetterMethod($methodName);
+		if ($isGetterMethod === FALSE) {
+			return;
+		}
+
+		if (MethodDocBlock::hasMethodDocBlock($file, $position) === FALSE) {
+			$file->addError('Getters should have docblock.', $position);
+			return;
+		}
+
+		$commentString = MethodDocBlock::getMethodDocBlock($file, $position);
+
+		if (strpos($commentString, '{@inheritdoc}') !== FALSE) {
+			return;
+		}
+
+		if (strpos($commentString, '@return') !== FALSE) {
+			return;
+		}
+
+		$file->addError('Getters should have @return tag (except {@inheritdoc}).', $position);
+	}
+
+
+	/**
+	 * @param string $methodName
+	 * @return bool
+	 */
+	private function guessIsGetterMethod($methodName)
+	{
+		foreach ($this->getterMethodPrefixes as $getterMethodPrefix) {
+			if (strpos($methodName, $getterMethodPrefix) === 0) {
+				if (strlen($methodName) === strlen($getterMethodPrefix)) {
+					return TRUE;
+				}
+
+				$endPosition = strlen($getterMethodPrefix);
+				$firstLetterAfterGetterPrefix = $methodName[$endPosition];
+
+				if (ctype_upper($firstLetterAfterGetterPrefix)) {
+					return TRUE;
+				}
+			}
+		}
+
+		return FALSE;
+	}
+
+}

src/ZenifyCodingStandard/Sniffs/Commenting/MethodCommentSniff.php

@@ -49,11 +49,7 @@ public function process(PHP_CodeSniffer_File $file, $position)
 			return;
 		}
 
-		$file->addError(
-			'Method docblock is missing, due to some parameters without typehints.',
-			$position,
-			'SpaceAfterLastUse'
-		);
+		$file->addError('Method docblock is missing, due to some parameters without typehints.', $position);
 	}
 
 

src/ZenifyCodingStandard/ruleset.xml

@@ -15,7 +15,6 @@
 	<rule ref="Generic.CodeAnalysis.UselessOverridingMethod"/>
 
 	<!-- Commenting -->
-	<rule ref="Squiz.Commenting.FunctionComment"/>
 	<rule ref="Squiz.Commenting.VariableComment"/>
 
 	<!-- ControlStructures -->

tests/Sniffs/Commenting/MethodCommentReturnTag/MethodCommentReturnTagSniffTest.php

@@ -0,0 +1,29 @@
+<?php
+
+namespace Zenify\CodingStandard\Tests\Sniffs\Commenting\MethodCommentReturnTag;
+
+use PHPUnit_Framework_TestCase;
+use Zenify\CodingStandard\Tests\CodeSnifferRunner;
+
+
+/**
+ * @covers ZenifyCodingStandard\Sniffs\Commenting\MethodCommentReturnTagSniff
+ */
+final class MethodCommentReturnTagSniffTest extends PHPUnit_Framework_TestCase
+{
+
+	public function testDetection()
+	{
+		$codeSnifferRunner = new CodeSnifferRunner('ZenifyCodingStandard.Commenting.MethodCommentReturnTag');
+
+		$this->assertSame(1, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/wrong.php'));
+		$this->assertSame(1, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/wrong2.php'));
+		$this->assertSame(0, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/correct.php'));
+		$this->assertSame(0, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/correct2.php'));
+		$this->assertSame(0, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/correct3.php'));
+		$this->assertSame(0, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/correct4.php'));
+		$this->assertSame(0, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/correct5.php'));
+		$this->assertSame(0, $codeSnifferRunner->getErrorCountInFile(__DIR__ . '/correct6.php'));
+	}
+
+}

tests/Sniffs/Commenting/MethodCommentReturnTag/correct2.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace SomeNamespace;
+
+use stdClass;
+
+
+class SomeClass
+{
+
+	public function __construct(stdClass $someClass)
+	{
+	}
+
+}

tests/Sniffs/Commenting/MethodCommentReturnTag/correct3.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace SomeNamespace;
+
+
+class SomeClass
+{
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function count($someClass)
+	{
+	}
+
+}

tests/Sniffs/Commenting/MethodCommentReturnTag/correct4.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace SomeNamespace;
+
+
+class SomeClass
+{
+
+	/**
+	 * @param bool $isRight
+	 */
+	public function count($isRight)
+	{
+	}
+
+}

tests/Sniffs/Commenting/MethodCommentReturnTag/correct5.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace SomeNamespace;
+
+
+class SomeClass
+{
+
+	public function isolate()
+	{
+	}
+
+}

tests/Sniffs/Commenting/MethodCommentReturnTag/correct6.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace SomeNamespace;
+
+
+class SomeClass
+{
+
+	/**
+	 * {@inheritdoc}
+	 */
+	public function isOk()
+	{
+	}
+
+}

tests/Sniffs/Commenting/MethodCommentReturnTag/wrong2.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace SomeNamespace;
+
+
+class SomeClass
+{
+
+	public function shouldGetSome()
+	{
+	}
+
+}