From a315761b4147902f8b24889d1d626f9845093187 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Micha=C5=82=20Bundyra?= <contact@webimpress.com>
Date: Wed, 13 Nov 2019 14:55:43 +0000
Subject: [PATCH] Feature: Commenting\DocComment sniff checks if there is a
 star in every line

Doc-block comment should have a star at the beginning of every line:

```php
/**
 * comment
 */
```

And the following example is invalid:

```php
/**
 comment
 */
```
---
 .../Sniffs/Commenting/DocCommentSniff.php     | 61 +++++++++++++++++++
 test/Sniffs/Commenting/DocCommentUnitTest.inc | 15 +++++
 .../Commenting/DocCommentUnitTest.inc.fixed   | 15 +++++
 test/Sniffs/Commenting/DocCommentUnitTest.php |  5 ++
 4 files changed, 96 insertions(+)

diff --git a/src/WebimpressCodingStandard/Sniffs/Commenting/DocCommentSniff.php b/src/WebimpressCodingStandard/Sniffs/Commenting/DocCommentSniff.php
index b15f02f7..59b1f805 100644
--- a/src/WebimpressCodingStandard/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/WebimpressCodingStandard/Sniffs/Commenting/DocCommentSniff.php
@@ -97,6 +97,7 @@ public function process(File $phpcsFile, $stackPtr)
 
         $this->checkSpacesAfterStar($phpcsFile, $commentStart, $commentEnd);
         $this->checkBlankLinesInComment($phpcsFile, $commentStart, $commentEnd);
+        $this->checkStarInEveryLine($phpcsFile, $commentStart, $commentEnd);
 
         $this->checkBlankLineBeforeTags($phpcsFile, $commentStart);
     }
@@ -584,6 +585,66 @@ private function checkSpacesAfterStar(File $phpcsFile, int $commentStart, int $c
         }
     }
 
+    private function checkStarInEveryLine(File $phpcsFile, int $commentStart, int $commentEnd) : void
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $firstLine = $tokens[$commentStart]['line'] + 1;
+        $lastLine = $tokens[$commentEnd]['line'] - 1;
+
+        $indentToken = $tokens[$commentStart - 1];
+        if ($indentToken['code'] === T_WHITESPACE
+            && $indentToken['line'] === $tokens[$commentStart]['line']
+        ) {
+            $indent = strlen($indentToken['content']) + 1;
+        } else {
+            $indent = 1;
+        }
+
+        $currentLine = $firstLine - 1;
+        for ($i = $commentStart; $i < $commentEnd; ++$i) {
+            $line = $tokens[$i]['line'];
+            if ($line > $lastLine) {
+                break;
+            }
+
+            if ($line === $currentLine + 1) {
+                $currentLine = $line;
+                if ($tokens[$i]['code'] === T_DOC_COMMENT_STAR) {
+                    continue;
+                }
+
+                if ($tokens[$i]['code'] === T_DOC_COMMENT_WHITESPACE
+                    && $tokens[$i + 1]['line'] === $line
+                    && $tokens[$i + 1]['code'] === T_DOC_COMMENT_STAR
+                ) {
+                    continue;
+                }
+
+                // blank line in a comment, skipping here
+                if ($tokens[$i]['code'] === T_DOC_COMMENT_WHITESPACE
+                    && $tokens[$i + 1]['line'] > $line
+                ) {
+                    continue;
+                }
+
+                $error = 'Missing star at the beginning doc-block comment line';
+                $fix = $phpcsFile->addFixableError($error, $i, 'MissingStar');
+
+                if ($fix) {
+                    if ($tokens[$i]['code'] === T_DOC_COMMENT_WHITESPACE) {
+                        $len = $tokens[$i]['length'];
+                        $spaces = max($len - $indent - 1, 1);
+                        $content = str_repeat(' ', $indent) . '*' . str_repeat(' ', $spaces);
+                        $phpcsFile->fixer->replaceToken($i, $content);
+                    } else {
+                        $phpcsFile->fixer->addContentBefore($i, str_repeat(' ', $indent) . '* ');
+                    }
+                }
+            }
+        }
+    }
+
     /**
      * Doc comment cannot have empty line on the beginning of the comment, at the end of the comment,
      * and there is allowed only one empty line between two comment sections.
diff --git a/test/Sniffs/Commenting/DocCommentUnitTest.inc b/test/Sniffs/Commenting/DocCommentUnitTest.inc
index 62eaf862..fa95409d 100644
--- a/test/Sniffs/Commenting/DocCommentUnitTest.inc
+++ b/test/Sniffs/Commenting/DocCommentUnitTest.inc
@@ -324,3 +324,18 @@ class Foo
     {
     }
 }
+
+/**
+hey
+hello
+ */
+
+/**
+    hi
+    hello
+ */
+
+/**
+ @var int $param
+ */
+$param = 1;
diff --git a/test/Sniffs/Commenting/DocCommentUnitTest.inc.fixed b/test/Sniffs/Commenting/DocCommentUnitTest.inc.fixed
index 3fd49c91..d377ac00 100644
--- a/test/Sniffs/Commenting/DocCommentUnitTest.inc.fixed
+++ b/test/Sniffs/Commenting/DocCommentUnitTest.inc.fixed
@@ -326,3 +326,18 @@ $c = 'xyz';
     {
     }
 }
+
+/**
+ * hey
+ * hello
+ */
+
+/**
+ * hi
+ *  hello
+ */
+
+/**
+ * @var int $param
+ */
+$param = 1;
diff --git a/test/Sniffs/Commenting/DocCommentUnitTest.php b/test/Sniffs/Commenting/DocCommentUnitTest.php
index f7a9ff08..098de77f 100644
--- a/test/Sniffs/Commenting/DocCommentUnitTest.php
+++ b/test/Sniffs/Commenting/DocCommentUnitTest.php
@@ -182,6 +182,11 @@ protected function getErrorList(string $testFile = '') : array
             260 => 1,
             320 => 1,
             322 => 1,
+            329 => 1,
+            330 => 1,
+            334 => 1,
+            335 => 1,
+            339 => 1,
         ];
     }