Skip to content

Commit 137a61d

Browse files
VincentLangletVincentLanglet
authored
Merge pull request #45 from VincentLanglet/commentTagRule
Comment tag rule
2 parents b1d2f55 + 34732e7 commit 137a61d

9 files changed

+250
-29
lines changed

‎SymfonyCustom/Sniffs/WhiteSpace/DocCommentTagSpacingSniff.php

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
<?php
2+
3+
namespace SymfonyCustom\Sniffs\WhiteSpace;
4+
5+
use PHP_CodeSniffer\Files\File;
6+
use PHP_CodeSniffer\Sniffs\Sniff;
7+
8+
/**
9+
* Checks that there are not 2 empty lines following each other.
10+
*/
11+
class DocCommentTagSpacingSniff implements Sniff
12+
{
13+
/**
14+
* Returns an array of tokens this test wants to listen for.
15+
*
16+
* @return array
17+
*/
18+
public function register()
19+
{
20+
return array(
21+
T_DOC_COMMENT_TAG
22+
);
23+
}
24+
25+
/**
26+
* Processes this test, when one of its tokens is encountered.
27+
*
28+
* @param File $phpcsFile The file being scanned.
29+
* @param int $stackPtr The position of the current token in the stack passed in $tokens.
30+
*
31+
* @return void
32+
*/
33+
public function process(File $phpcsFile, $stackPtr)
34+
{
35+
$tokens = $phpcsFile->getTokens();
36+
37+
if (!isset($tokens[($stackPtr - 1)]) || T_DOC_COMMENT_WHITESPACE !== $tokens[($stackPtr - 1)]['code']) {
38+
$error = 'There should be a space before a doc comment tag "%s"';
39+
$fix = $phpcsFile->addFixableError(
40+
$error,
41+
($stackPtr - 1),
42+
'DocCommentTagSpacing',
43+
array($tokens[$stackPtr]['content'])
44+
);
45+
46+
if (true === $fix) {
47+
$phpcsFile->fixer->addContentBefore($stackPtr, ' ');
48+
}
49+
} elseif (1 !== $tokens[($stackPtr - 1)]['length']) {
50+
$error = 'There should be only one space before a doc comment tag "%s"';
51+
$fix = $phpcsFile->addFixableError(
52+
$error,
53+
($stackPtr + 1),
54+
'DocCommentTagSpacing',
55+
array($tokens[$stackPtr]['content'])
56+
);
57+
58+
if (true === $fix) {
59+
$phpcsFile->fixer->replaceToken($stackPtr - 1, ' ');
60+
}
61+
}
62+
63+
// No need to check for space after a doc comment tag
64+
if (isset($tokens[($stackPtr + 1)])
65+
&& T_DOC_COMMENT_WHITESPACE === $tokens[($stackPtr + 1)]['code']
66+
&& 1 !== $tokens[($stackPtr + 1)]['length']
67+
) {
68+
$error = 'There should be only one space after a doc comment tag "%s"';
69+
$fix = $phpcsFile->addFixableError(
70+
$error,
71+
($stackPtr + 1),
72+
'DocCommentTagSpacing',
73+
array($tokens[$stackPtr]['content'])
74+
);
75+
76+
if (true === $fix) {
77+
$phpcsFile->fixer->replaceToken($stackPtr + 1, ' ');
78+
}
79+
}
80+
}
81+
}

‎SymfonyCustom/Tests/Commenting/VariableCommentUnitTest.inc

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ class VariableCommentUnitTest
120120
*
121121
*
122122
*/
123-
public $emptyVarDoc = '';
123+
public $emptyVarDoc = '';
124124
/**
125125
* @var int
126126
*/

‎SymfonyCustom/Tests/Commenting/VariableCommentUnitTest.inc.fixed

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ class VariableCommentUnitTest
120120
*
121121
*
122122
*/
123-
public $emptyVarDoc = '';
123+
public $emptyVarDoc = '';
124124

125125
/**
126126
* @var int

‎SymfonyCustom/Tests/WhiteSpace/DocCommentTagSpacingUnitTest.inc

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<?php
2+
3+
class DocCommentTagSpacingUnitTest
4+
{
5+
/**
6+
* Short description of the member variable.
7+
*
8+
* Long description of member variable. Can span over multiple
9+
* lines and can have multiple paragraphs.
10+
*
11+
*@var array
12+
*
13+
* @see otherFunctions()
14+
* @see anotherFunctions()
15+
*/
16+
public $variableName = array();
17+
18+
/**
19+
* T_VARIABLE check, var in string and in function.
20+
*
21+
*@param integer $var1 First variable.
22+
* @param integer $var2 Second variable.
23+
*
24+
* @return integer
25+
*/
26+
protected function checkFunction($var1, $var2)
27+
{
28+
/**@var int $var3 */
29+
$var3 = $var1 + $var2;
30+
31+
return $var3;
32+
}
33+
}

‎SymfonyCustom/Tests/WhiteSpace/DocCommentTagSpacingUnitTest.inc.fixed

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<?php
2+
3+
class DocCommentTagSpacingUnitTest
4+
{
5+
/**
6+
* Short description of the member variable.
7+
*
8+
* Long description of member variable. Can span over multiple
9+
* lines and can have multiple paragraphs.
10+
*
11+
* @var array
12+
*
13+
* @see otherFunctions()
14+
* @see anotherFunctions()
15+
*/
16+
public $variableName = array();
17+
18+
/**
19+
* T_VARIABLE check, var in string and in function.
20+
*
21+
* @param integer $var1 First variable.
22+
* @param integer $var2 Second variable.
23+
*
24+
* @return integer
25+
*/
26+
protected function checkFunction($var1, $var2)
27+
{
28+
/** @var int $var3 */
29+
$var3 = $var1 + $var2;
30+
31+
return $var3;
32+
}
33+
}

‎SymfonyCustom/Tests/WhiteSpace/DocCommentTagSpacingUnitTest.php

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<?php
2+
3+
namespace SymfonyCustom\Tests\WhiteSpace;
4+
5+
use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
6+
7+
/**
8+
* Unit test class for the CloseBracketSpacing sniff.
9+
*
10+
* @group SymfonyCustom
11+
*/
12+
class DocCommentTagSpacingUnitTest extends AbstractSniffUnitTest
13+
{
14+
/**
15+
* Returns the lines where errors should occur.
16+
*
17+
* The key of the array should represent the line number and the value
18+
* should represent the number of errors that should occur on that line.
19+
*
20+
* @return array<int, int>
21+
*/
22+
public function getErrorList()
23+
{
24+
return array(
25+
11 => 1,
26+
13 => 1,
27+
14 => 1,
28+
21 => 1,
29+
22 => 1,
30+
24 => 1,
31+
28 => 1,
32+
);
33+
}
34+
35+
/**
36+
* Returns the lines where warnings should occur.
37+
*
38+
* The key of the array should represent the line number and the value
39+
* should represent the number of warnings that should occur on that line.
40+
*
41+
* @return array(int => int)
42+
*/
43+
protected function getWarningList()
44+
{
45+
return array();
46+
}
47+
}

‎SymfonyCustom/ruleset.xml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55

66
<!-- We should only be concerned by src and tests folder -->
77
<exclude-pattern>*/app/*</exclude-pattern>
8+
<exclude-pattern>*/bin/*</exclude-pattern>
89
<exclude-pattern>*/var/*</exclude-pattern>
910
<exclude-pattern>*/vendor/*</exclude-pattern>
1011
<exclude-pattern>*/web/*</exclude-pattern>
@@ -31,6 +32,15 @@
3132
<severity>5</severity>
3233
</rule>
3334

35+
<!-- Override ScopeIndent to check phpDoc comments indent-->
36+
<rule ref="Generic.WhiteSpace.ScopeIndent">
37+
<properties>
38+
<property name="ignoreIndentationTokens" type="array">
39+
<element value="T_COMMENT"/>
40+
</property>
41+
</properties>
42+
</rule>
43+
3444
<!-- **************** -->
3545
<!-- *** OTHERS *** -->
3646
<!-- **************** -->

‎docs/standards.md

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,17 @@ We imported the [PSR2 Standard](./standards/psr2.md) with these overrides:
2121
</rule>
2222
```
2323

24+
- PhpDoc comments MUSE use an indent of 4 spaces, and MUST NOT use tabs for indenting.
25+
```
26+
<rule ref="Generic.WhiteSpace.ScopeIndent">
27+
<properties>
28+
<property name="ignoreIndentationTokens" type="array">
29+
<element value="T_COMMENT"/>
30+
</property>
31+
</properties>
32+
</rule>
33+
```
34+
2435
## From symfony
2536

2637
We mainly respect the [Symfony Standard](./standards/symfony.md) but
@@ -136,3 +147,9 @@ we do not respect this rule:
136147
```
137148
<rule ref="SymfonyCustom.Namespaces.UnusedUse"/>
138149
```
150+
151+
- Add a single space around comment tag (`@var`, `@return`, `...`)
152+
153+
```
154+
<rule ref="SymfonyCustom.WhiteSpace.DocCommentTagSpacing"/>
155+
```

0 commit comments

Comments
 (0)