Merge pull request #46 from GrandLTU/field_name

Field names should be omitted in class field documentation.

Sniffs/Commenting/VariableCommentSniff.php

@@ -252,7 +252,7 @@ protected function processVar($commentStart, $commentEnd)
                 } elseif ($suggestedType === 'integer') {
                     $suggestedType = 'int';
                 }
-                if ($content !== $suggestedType) {
+                if ($content !== $suggestedType && strpos($content, $suggestedType . ' ') === false) {
                     $error = 'Expected "%s"; found "%s" for @var tag in variable comment';
                     $data = [
                         $suggestedType,
@@ -362,6 +362,15 @@ protected function processVarComment(PHP_CodeSniffer_CommentParser_SingleElement
             return;
         }
 
+        if (substr($comment, 0, 1) == '$') {
+            $this->currentFile->addError(
+                'Class field docs should not contain field name',
+                $errorPos
+            );
+
+            return;
+        }
+
         if (!in_array(substr($comment, -1, 1), ['.', '?', '!'])) {
             $this->currentFile->addError(
                 'Variable comments must end in full-stops, exclamation marks, or question marks',

Tests/Unit/Commenting/VariableCommentSniffTest.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the ONGR package.
+ *
+ * (c) NFQ Technologies UAB <info@nfq.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace ONGR\Tests\Unit\Commenting;
+
+use ONGR\Tests\AbstractSniffUnitTest;
+
+/**
+ * VariableCommentSniffTest class.
+ */
+class VariableCommentSniffTest extends AbstractSniffUnitTest
+{
+    /**
+     * {@inheritdoc}
+     */
+    protected function getErrorList()
+    {
+        return [
+            22 => ['Class field docs should not contain field name'],
+            27 => ['Class field docs should not contain field name'],
+            42 => ['Class field docs should not contain field name'],
+            47 => ['Class field docs should not contain field name'],
+            57 => ['Expected "array(string => array)"; found "array(string => array())'],
+            62 => ['Variable comments must end in full-stops, exclamation marks, or question marks'],
+            78 => ['Only 1 @var tag is allowed in variable comment'],
+            // Multiple declarations not allowed but doc check for second variable still fires and fails.
+            80 => ['Missing variable doc comment'],
+        ];
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getWarningList()
+    {
+        return [];
+    }
+}

Tests/Unit/Commenting/VariableCommentSniffTest.phptest

@@ -0,0 +1,81 @@
+<?php
+
+/*
+ * This file is part of the ONGR package.
+ *
+ * (c) NFQ Technologies UAB <info@nfq.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Test;
+
+class VariableCommentSniffTest
+{
+    /**
+     * @var int
+     */
+    public $foo;
+
+    /**
+     * @var int $bar
+     */
+    public $bar;
+
+    /**
+     * @var int $fooBar This is fooBar.
+     */
+    public $fooBar;
+
+    /**
+     * @var int This is barFoo.
+     */
+    public $barFoo;
+
+    /**
+     * @var array(string => string|null) This is fooBar2.
+     */
+    public $fooBar2;
+
+    /**
+     * @var array(string => string|array) $fooBar3 This is fooBar3.
+     */
+    public $fooBar3;
+
+    /**
+     * @var array(string => string|null) $fooBar4
+     */
+    public $fooBar4;
+
+    /**
+     * @var array(string => string|null)
+     */
+    public $fooBar5;
+
+    /**
+     * @var array(string => array())
+     */
+    public $fooBar6;
+
+    /**
+     * @var int This is fooBar7
+     */
+    public $fooBar7;
+
+    /**
+     * @var int This is fooBar8!
+     */
+    public $fooBar8;
+
+    /**
+     * @var int This is fooBar9?
+     */
+    public $fooBar9;
+
+    /**
+     * @var int $bar2
+     * @var int $foo2 Bar.
+     */
+    protected $bar2, $foo2;
+}